@lifi/sdk 0.0.0-preview-f5cf9f8

package/src/utils/convertQuoteToRoute.ts

@@ -0,0 +1,154 @@
+import type { LiFiStep, Route, Step } from '@lifi/types'
+import { ValidationError } from '../errors/errors.js'
+import { SDKError } from '../errors/SDKError.js'
+import { formatUnits } from './formatUnits.js'
+
+interface ConvertQuoteToRouteOptions {
+  /**
+   * When true, if the quote has zero output values (toAmount, toAmountMin, toAmountUSD),
+   * use the values from the previous included step that has non-zero output.
+   */
+  adjustZeroOutputFromPreviousStep?: boolean
+}
+
+const parseBigInt = (value: string | undefined): bigint => {
+  if (!value) {
+    return 0n
+  }
+  try {
+    return BigInt(value)
+  } catch {
+    return 0n
+  }
+}
+
+const parseNumber = (value: string | undefined): number => {
+  if (!value) {
+    return 0
+  }
+  const parsed = Number(value)
+  return Number.isNaN(parsed) ? 0 : parsed
+}
+
+const isZeroOutput = (
+  toAmount: string,
+  toAmountMin: string,
+  toAmountUSD?: string
+): boolean => {
+  return (
+    !parseBigInt(toAmount) &&
+    !parseBigInt(toAmountMin) &&
+    !parseNumber(toAmountUSD)
+  )
+}
+
+const hasNonZeroOutput = (step: Step): boolean => {
+  return (
+    !!parseBigInt(step.estimate.toAmount) ||
+    !!parseBigInt(step.estimate.toAmountMin)
+  )
+}
+
+const findPreviousNonZeroStep = (steps: Step[]): Step | undefined => {
+  // Find the last step that has non-zero output (the step before the zero output step)
+  for (let i = steps.length - 1; i >= 0; i--) {
+    const step = steps[i]
+    if (hasNonZeroOutput(step)) {
+      return step
+    }
+  }
+  return undefined
+}
+
+export function formatTokenPrice(
+  amount?: string | bigint,
+  price?: string,
+  decimals?: number
+): number {
+  if (!amount || !price) {
+    return 0
+  }
+
+  const formattedAmount =
+    typeof amount === 'bigint' && decimals !== undefined
+      ? formatUnits(amount, decimals)
+      : amount.toString()
+
+  if (Number.isNaN(Number(formattedAmount)) || Number.isNaN(Number(price))) {
+    return 0
+  }
+  return Number.parseFloat(formattedAmount) * Number.parseFloat(price)
+}
+
+/**
+ * Converts a quote to Route
+ * @param quote - Step returned from the quote endpoint.
+ * @param options - Optional configuration for handling edge cases.
+ * @returns - The route to be executed.
+ * @throws {BaseError} Throws a ValidationError if the step has missing values.
+ */
+export const convertQuoteToRoute = (
+  quote: LiFiStep,
+  options?: ConvertQuoteToRouteOptions
+): Route => {
+  let toAmount = quote.estimate.toAmount
+  let toAmountMin = quote.estimate.toAmountMin
+  let toAmountUSD = quote.estimate.toAmountUSD
+
+  // Handle zero output values by looking at previous included step
+  if (
+    options?.adjustZeroOutputFromPreviousStep &&
+    quote.includedSteps?.length &&
+    isZeroOutput(toAmount, toAmountMin, toAmountUSD)
+  ) {
+    const previousStep = findPreviousNonZeroStep(quote.includedSteps)
+    if (previousStep) {
+      toAmount = previousStep.estimate.toAmount
+      toAmountMin = previousStep.estimate.toAmountMin
+      toAmountUSD = formatTokenPrice(
+        parseBigInt(toAmount),
+        previousStep.action.toToken.priceUSD,
+        previousStep.action.toToken.decimals
+      ).toFixed(2)
+
+      // Update the last included step's estimate with the adjusted values
+      const lastStep = quote.includedSteps[quote.includedSteps.length - 1]
+      if (lastStep && !hasNonZeroOutput(lastStep)) {
+        lastStep.estimate.toAmount = toAmount
+        lastStep.estimate.toAmountMin = toAmountMin
+      }
+    }
+  }
+
+  if (!quote.estimate.fromAmountUSD) {
+    throw new SDKError(
+      new ValidationError("Missing 'fromAmountUSD' in step estimate.")
+    )
+  }
+
+  if (!toAmountUSD) {
+    throw new SDKError(
+      new ValidationError("Missing 'toAmountUSD' in step estimate.")
+    )
+  }
+
+  const route: Route = {
+    id: quote.id,
+    fromChainId: quote.action.fromToken.chainId,
+    fromToken: quote.action.fromToken,
+    fromAmount: quote.action.fromAmount,
+    fromAmountUSD: quote.estimate.fromAmountUSD,
+    fromAddress: quote.action.fromAddress,
+    toChainId: quote.action.toToken.chainId,
+    toToken: quote.action.toToken,
+    toAmount,
+    toAmountMin,
+    toAmountUSD,
+    toAddress: quote.action.toAddress || quote.action.fromAddress,
+    gasCostUSD: quote.estimate.gasCosts?.[0]?.amountUSD || '0',
+    steps: [quote],
+    insurance: { state: 'NOT_INSURABLE', feeAmountUsd: '0' },
+  }
+
+  return route
+}

package/src/utils/decode.ts

@@ -0,0 +1,13 @@
+export const decodeTaskId = (taskId: string): string[] => {
+  const decoded = new TextDecoder()
+    .decode(
+      new Uint8Array(
+        taskId
+          .slice(2)
+          .match(/.{1,2}/g)
+          ?.map((byte) => Number.parseInt(byte, 16)) ?? []
+      )
+    )
+    .split('|')
+  return decoded
+}

package/src/utils/fetchTxErrorDetails.ts

@@ -0,0 +1,15 @@
+export const fetchTxErrorDetails = async (
+  txHash: string,
+  chainId: number
+): Promise<unknown> => {
+  try {
+    const response = await fetch(
+      `https://api.tenderly.co/api/v1/public-contract/${chainId}/tx/${txHash}`
+    )
+    const reponseBody = await response.json()
+
+    return reponseBody
+  } catch (_) {
+    return undefined
+  }
+}

package/src/utils/formatUnits.ts

@@ -0,0 +1,22 @@
+/**
+ *  Divides a number by a given exponent of base 10 (10exponent), and formats it into a string representation of the number.
+ */
+export function formatUnits(value: bigint, decimals: number): string {
+  let display = value.toString()
+
+  const negative = display.startsWith('-')
+  if (negative) {
+    display = display.slice(1)
+  }
+
+  display = display.padStart(decimals, '0')
+
+  let [integer, fraction] = [
+    display.slice(0, display.length - decimals),
+    display.slice(display.length - decimals),
+  ]
+  fraction = fraction.replace(/(0+)$/, '')
+  return `${negative ? '-' : ''}${integer || '0'}${
+    fraction ? `.${fraction}` : ''
+  }`
+}

package/src/utils/getTransactionMessage.ts

@@ -0,0 +1,17 @@
+import type { LiFiStep } from '@lifi/types'
+import type { SDKClient } from '../types/core.js'
+
+export const getTransactionFailedMessage = async (
+  client: SDKClient,
+  step: LiFiStep,
+  txLink?: string
+): Promise<string> => {
+  const chain = await client.getChainById(step.action.toChainId)
+
+  const baseString = `It appears that your transaction may not have been successful.
+  However, to confirm this, please check your ${chain.name} wallet for ${step.action.toToken.symbol}.`
+  return txLink
+    ? `${baseString}
+    You can also check the&nbsp;<a href="${txLink}" target="_blank" rel="nofollow noreferrer">block explorer</a> for more information.`
+    : baseString
+}

package/src/utils/isHex.ts

@@ -0,0 +1,14 @@
+export type Hex = `0x${string}`
+
+export function isHex(
+  value: unknown,
+  { strict = true }: { strict?: boolean | undefined } = {}
+): value is Hex {
+  if (!value) {
+    return false
+  }
+  if (typeof value !== 'string') {
+    return false
+  }
+  return strict ? /^0x[0-9a-fA-F]*$/.test(value) : value.startsWith('0x')
+}

package/src/utils/isRoutesRequest.ts

@@ -0,0 +1,31 @@
+import type { RouteOptions, RoutesRequest } from '@lifi/types'
+
+const isRoutesOptions = (
+  routeOptions: RouteOptions
+): routeOptions is RouteOptions =>
+  !routeOptions?.slippage || typeof routeOptions.slippage === 'number'
+
+export const isRoutesRequest = (
+  routesRequest: RoutesRequest
+): routesRequest is RoutesRequest => {
+  const {
+    fromChainId,
+    fromAmount,
+    fromTokenAddress,
+    toChainId,
+    toTokenAddress,
+    options,
+  } = routesRequest
+
+  return (
+    typeof fromChainId === 'number' &&
+    typeof fromAmount === 'string' &&
+    fromAmount !== '' &&
+    typeof fromTokenAddress === 'string' &&
+    fromTokenAddress !== '' &&
+    typeof toChainId === 'number' &&
+    typeof toTokenAddress === 'string' &&
+    toTokenAddress !== '' &&
+    (!options || isRoutesOptions(options))
+  )
+}

package/src/utils/isStep.ts

@@ -0,0 +1,41 @@
+import type { Action, Estimate, LiFiStep } from '@lifi/types'
+import { isToken } from './isToken.js'
+
+const isAction = (action: Action): action is Action => {
+  const { fromChainId, fromAmount, fromToken, toChainId, toToken } = action
+
+  return (
+    typeof fromChainId === 'number' &&
+    typeof fromAmount === 'string' &&
+    fromAmount !== '' &&
+    isToken(fromToken) &&
+    typeof toChainId === 'number' &&
+    isToken(toToken)
+  )
+}
+
+const isEstimate = (estimate: Estimate): estimate is Estimate => {
+  const { fromAmount, toAmount, toAmountMin, approvalAddress } = estimate
+
+  return (
+    typeof fromAmount === 'string' &&
+    fromAmount !== '' &&
+    typeof toAmount === 'string' &&
+    toAmount !== '' &&
+    typeof toAmountMin === 'string' &&
+    toAmountMin !== '' &&
+    (typeof approvalAddress === 'string' || approvalAddress === null)
+  )
+}
+
+export const isStep = (step: LiFiStep): step is LiFiStep => {
+  const { id, type, tool, action, estimate } = step
+
+  return (
+    typeof id === 'string' &&
+    ['swap', 'cross', 'lifi'].includes(type) &&
+    typeof tool === 'string' &&
+    isAction(action) &&
+    isEstimate(estimate)
+  )
+}

package/src/utils/isToken.ts

@@ -0,0 +1,11 @@
+import type { StaticToken } from '@lifi/types'
+
+export const isToken = (token: StaticToken): token is StaticToken => {
+  const { address, decimals, chainId } = token
+
+  return (
+    typeof address === 'string' &&
+    typeof decimals === 'number' &&
+    typeof chainId === 'number'
+  )
+}

package/src/utils/parseUnits.ts

@@ -0,0 +1,50 @@
+/**
+ * Multiplies a string representation of a number by a given exponent of base 10 (10exponent).
+ */
+export function parseUnits(value: string, decimals: number): bigint {
+  if (!/^(-?)([0-9]*)\.?([0-9]*)$/.test(value)) {
+    throw new Error(`Number \`${value}\` is not a valid decimal number.`)
+  }
+
+  let [integer, fraction = '0'] = value.split('.')
+
+  const negative = integer.startsWith('-')
+  if (negative) {
+    integer = integer.slice(1)
+  }
+
+  // trim trailing zeros.
+  fraction = fraction.replace(/(0+)$/, '')
+
+  // round off if the fraction is larger than the number of decimals.
+  if (decimals === 0) {
+    if (Math.round(Number(`.${fraction}`)) === 1) {
+      integer = `${BigInt(integer) + 1n}`
+    }
+    fraction = ''
+  } else if (fraction.length > decimals) {
+    const [left, unit, right] = [
+      fraction.slice(0, decimals - 1),
+      fraction.slice(decimals - 1, decimals),
+      fraction.slice(decimals),
+    ]
+
+    const rounded = Math.round(Number(`${unit}.${right}`))
+    if (rounded > 9) {
+      fraction = `${BigInt(left) + BigInt(1)}0`.padStart(left.length + 1, '0')
+    } else {
+      fraction = `${left}${rounded}`
+    }
+
+    if (fraction.length > decimals) {
+      fraction = fraction.slice(1)
+      integer = `${BigInt(integer) + 1n}`
+    }
+
+    fraction = fraction.slice(0, decimals)
+  } else {
+    fraction = fraction.padEnd(decimals, '0')
+  }
+
+  return BigInt(`${negative ? '-' : ''}${integer}${fraction}`)
+}

package/src/utils/request.ts

@@ -0,0 +1,100 @@
+import { ValidationError } from '../errors/errors.js'
+import { HTTPError } from '../errors/httpError.js'
+import { SDKError } from '../errors/SDKError.js'
+import type { SDKBaseConfig } from '../types/core.js'
+import type { ExtendedRequestInit } from '../types/request.js'
+import { version } from '../version.js'
+import { sleep } from './sleep.js'
+
+export const requestSettings = {
+  retries: 1,
+}
+
+const stripExtendRequestInitProperties = ({
+  retries,
+  ...rest
+}: ExtendedRequestInit): RequestInit => ({
+  ...rest,
+})
+
+export const request = async <T = Response>(
+  config: SDKBaseConfig,
+  url: RequestInfo | URL,
+  options: ExtendedRequestInit = {
+    retries: requestSettings.retries,
+  }
+): Promise<T> => {
+  const { userId, integrator, widgetVersion, apiKey, requestInterceptor } =
+    config
+
+  if (!integrator) {
+    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 (apiKey) {
+      options.headers = {
+        ...options.headers,
+        'x-lifi-api-key': apiKey,
+      }
+    }
+
+    if (userId) {
+      options.headers = {
+        ...options.headers,
+        'x-lifi-userid': userId,
+      }
+    }
+
+    if (widgetVersion) {
+      options.headers = {
+        ...options.headers,
+        'x-lifi-widget': widgetVersion,
+      }
+    }
+
+    if (version) {
+      options.headers = {
+        ...options.headers,
+        'x-lifi-sdk': version,
+      }
+    }
+
+    // integrator is mandatory during SDK initialization
+    options.headers = {
+      ...options.headers,
+      'x-lifi-integrator': integrator,
+    }
+
+    if (requestInterceptor) {
+      options = await requestInterceptor(options)
+    }
+
+    const response: Response = await fetch(
+      url,
+      stripExtendRequestInitProperties(options)
+    )
+
+    if (!response.ok) {
+      throw new HTTPError(response, url, options)
+    }
+
+    return await response.json()
+  } catch (error) {
+    const retries = options.retries ?? 0
+    if (retries > 0 && (error as HTTPError).status === 500) {
+      await sleep(500)
+      return request<T>(config, url, { ...options, retries: retries - 1 })
+    }
+
+    await (error as HTTPError).buildAdditionalDetails?.()
+
+    throw new SDKError(error as HTTPError)
+  }
+}

package/src/utils/sleep.ts

@@ -0,0 +1,5 @@
+export function sleep(ms: number): Promise<null> {
+  return new Promise((resolve) => {
+    setTimeout(() => resolve(null), ms)
+  })
+}

package/src/utils/waitForResult.ts

@@ -0,0 +1,45 @@
+import { sleep } from './sleep.js'
+
+/**
+ * Repeatedly calls a given asynchronous function until it resolves with a value
+ * @param fn The function that should be repeated
+ * @param interval The timeout in milliseconds between retries, or a function that receives the current poll count and returns the interval. Defaults to 5000
+ * @param maxRetries Maximum number of retries before throwing an error, defaults to 3
+ * @param shouldRetry Optional predicate to determine if an error should trigger a retry
+ * @returns The result of the fn function
+ * @throws Error if maximum retries is reached, if function keeps returning undefined, or if shouldRetry returns false
+ */
+export const waitForResult = async <T>(
+  fn: () => Promise<T | undefined>,
+  interval: number | ((poll: number) => number) = 5000,
+  maxRetries = 3,
+  shouldRetry: (count: number, error: unknown) => boolean = () => true
+): Promise<T> => {
+  let result: T | undefined
+  let attempts = 0
+  let polls = 0
+
+  const getInterval = typeof interval === 'function' ? interval : () => interval
+
+  while (!result) {
+    try {
+      result = await fn()
+      if (!result) {
+        await sleep(getInterval(polls))
+        polls++
+      }
+    } catch (error) {
+      if (!shouldRetry(attempts, error)) {
+        throw error
+      }
+      attempts++
+      if (attempts === maxRetries) {
+        throw error
+      }
+      await sleep(getInterval(polls))
+      polls++
+    }
+  }
+
+  return result
+}

package/src/utils/withDedupe.ts

@@ -0,0 +1,45 @@
+/**
+ * Map with a LRU (Least recently used) policy.
+ *
+ * https://en.wikipedia.org/wiki/Cache_replacement_policies#LRU
+ */
+export class LruMap<value = unknown> extends Map<string, value> {
+  maxSize: number
+
+  constructor(size: number) {
+    super()
+    this.maxSize = size
+  }
+
+  override set(key: string, value: value): this {
+    super.set(key, value)
+    if (this.maxSize && this.size > this.maxSize) {
+      this.delete(this.keys().next().value!)
+    }
+    return this
+  }
+}
+
+/** @internal */
+const promiseCache = /*#__PURE__*/ new LruMap<Promise<any>>(8192)
+
+type WithDedupeOptions = {
+  enabled?: boolean | undefined
+  id?: string | undefined
+}
+
+/** Deduplicates in-flight promises. */
+export function withDedupe<T>(
+  fn: () => Promise<T>,
+  { enabled = true, id }: WithDedupeOptions
+): Promise<T> {
+  if (!enabled || !id) {
+    return fn()
+  }
+  if (promiseCache.get(id)) {
+    return promiseCache.get(id)!
+  }
+  const promise = fn().finally(() => promiseCache.delete(id))
+  promiseCache.set(id, promise)
+  return promise
+}

package/src/utils/withTimeout.ts

@@ -0,0 +1,50 @@
+/**
+ * Wraps a function in a timeout.
+ * Based on viem's withTimeout implementation.
+ * @param fn - The function to wrap.
+ * @param timeout - The timeout in milliseconds.
+ * @param errorInstance - The error instance to throw when the timeout is reached.
+ * @param signal - Whether or not the timeout should use an abort signal.
+ * @returns The result of the function.
+ */
+export function withTimeout<T>(
+  fn: ({ signal }: { signal: AbortController['signal'] | null }) => Promise<T>,
+  {
+    errorInstance = new Error('Timed out after waiting for too long.'),
+    timeout,
+    signal,
+  }: {
+    // The error instance to throw when the timeout is reached.
+    errorInstance?: Error | undefined
+    // The timeout (in ms).
+    timeout: number
+    // Whether or not the timeout should use an abort signal.
+    signal?: boolean | undefined
+  }
+): Promise<T> {
+  return new Promise((resolve, reject) => {
+    ;(async () => {
+      let timeoutId!: NodeJS.Timeout
+      try {
+        const controller = new AbortController()
+        if (timeout > 0) {
+          timeoutId = setTimeout(() => {
+            if (signal) {
+              controller.abort()
+            } else {
+              reject(errorInstance)
+            }
+          }, timeout) as NodeJS.Timeout // need to cast because bun globals.d.ts overrides @types/node
+        }
+        resolve(await fn({ signal: controller?.signal || null }))
+      } catch (err) {
+        if ((err as Error)?.name === 'AbortError') {
+          reject(errorInstance)
+        }
+        reject(err)
+      } finally {
+        clearTimeout(timeoutId)
+      }
+    })()
+  })
+}

package/src/version.ts

@@ -0,0 +1,2 @@
+export const name = '@lifi/sdk'
+export const version = '0.0.0-preview-f5cf9f8'