@chainlink/external-adapter-framework 0.0.14 → 0.0.15

package/src/examples/bank-frick/accounts.ts

@@ -0,0 +1,246 @@
+import axios, { AxiosRequestConfig, AxiosResponse } from 'axios'
+import {
+  Account,
+  AdapterInputParameters,
+  BankFrickAccountsRequestSchema,
+  BankFrickAccountsResponseSchema,
+  SigningAlgorithm,
+} from './types'
+import { customSettings } from './config'
+import { Transport } from '../../transports'
+import { generateJWT } from './util'
+import { AdapterRequest, AdapterResponse, makeLogger, sleep } from '../../util'
+import { AdapterConfig } from '../../config'
+import { AdapterError } from '../../validation/error'
+import { Cache } from '../../cache'
+import { InputParameters } from '../../validation'
+import { AdapterDependencies, AdapterEndpoint } from '../../adapter'
+
+const logger = makeLogger('BankFrickTransport')
+
+// Note: this is a shallow pattern that only checks for a country code since IBANs in the sandbox are invalid
+const ibanPattern = /^[A-Z]{2}[A-Z\d]{14,30}$/
+const inputParameters: InputParameters = {
+  ibanIDs: {
+    description: 'The list of account ids included in the sum of balances',
+    required: true,
+    type: 'array',
+  },
+  signingAlgorithm: {
+    description:
+      'What signing algorithm is used to sign and verify authorization data, one of rsa-sha256, rsa-sha384, or rsa-sha512',
+    required: false,
+    type: 'string',
+    default: 'rsa-sha512',
+    options: ['rsa-sha256', 'rsa-sha384', 'rsa-sha512'],
+  },
+}
+
+// See here for all expected error returned by the API: https://developers.bankfrick.li/docs#errors
+const AuthErrors: { [key: number]: string } = {
+  401: 'No JWT token provided or token is invalid',
+  403: 'API key is invalid or any other condition is hindering the login', // Unclear if this is fatal or not
+}
+const FatalErrors: { [key: number]: string } = {
+  400: "Invalid parameters passed to Bank Frick's API",
+  423: "Authorization is valid, but the user's account is locked",
+}
+
+/**
+ * RestTransport implementation for Bank Frick, which has unusually complex requirements for an EA
+ * The RestTransport is generally built to make a single request and return a single response.
+ * This transport instead is used to fetch and process pages of data, and also requires a JWT to run
+ *
+ * This transport does all the heavy lifting in setup(), which is where the paging happens, and it
+ * also has complex retry logic that will attempt to refresh the JWT when certain HTTP errors occur
+ */
+export class BankFrickAccountsTransport
+  implements Transport<AdapterInputParameters, number, typeof customSettings>
+{
+  // Global variable to keep the token. Token is provisioned when the accounts endpoint is hit.
+  // Each instance of the EA will have their own token by design
+  token!: string
+  cache!: Cache
+
+  async initialize(dependencies: AdapterDependencies): Promise<void> {
+    this.cache = dependencies.cache
+  }
+
+  async hasBeenSetUp() {
+    return false // Return false since we aren't coalescing requests
+  }
+
+  /**
+   * Creates an AxiosRequestConfig object for fetching a page of accounts from the Bank Frick API
+   */
+  prepareRequest(
+    firstPosition: number,
+    inputParams: AdapterInputParameters,
+    config: AdapterConfig<typeof customSettings>,
+  ): AxiosRequestConfig<BankFrickAccountsRequestSchema> {
+    const { API_ENDPOINT, BASE_URL, PAGE_SIZE } = config
+
+    return {
+      baseURL: API_ENDPOINT + BASE_URL,
+      url: 'accounts',
+      method: 'GET',
+      params: {
+        firstPosition,
+        maxResults: PAGE_SIZE,
+      },
+      headers: {
+        Authorization: `Bearer ${this.token}`,
+      },
+    }
+  }
+
+  /**
+   * Request with retry logic for Bank Frick's API. In addition to standard retry logic, this function
+   * compares errors against expected errors from the Bank Frick API, and will throw without retries
+   * on a known fatal error, or try to refresh the JWT on a known auth error
+   **/
+  async makeRequest(
+    axiosRequest: AxiosRequestConfig<BankFrickAccountsRequestSchema>,
+    config: AdapterConfig<typeof customSettings>,
+    signingAlgorithm?: SigningAlgorithm,
+  ): Promise<AxiosResponse<BankFrickAccountsResponseSchema>> {
+    let retryNumber = 0
+    let response = await axios.request(axiosRequest)
+    while (response.status !== 200) {
+      retryNumber++
+      logger.warn(
+        'Encountered error when fetching accounts from Bank Frick:',
+        response.status,
+        response.statusText,
+      )
+
+      // Evaluate whether the error was fatal, auth, or transient and whether we've exceeded the max number of retries.
+      // Throw on fatal, refresh token on auth error, pass on transient until we've exhausted our retries
+      if (FatalErrors[response.status]) {
+        throw new AdapterError({
+          statusCode: response.status,
+          message: response.statusText,
+        })
+      } else if (AuthErrors[response.status]) {
+        // We've encountered a known auth error, so try to refresh the token before making another request
+        logger.info('Auth error received from the Bank Frick API, attempting to refresh the token')
+        this.token = await generateJWT(config, signingAlgorithm)
+      } else if (retryNumber === config.REST_TRANSPORT_MAX_RATE_LIMIT_RETRIES) {
+        throw new AdapterError({
+          statusCode: 504,
+          message: `Bank Frick transport hit the max number of retries (${config.REST_TRANSPORT_MAX_RATE_LIMIT_RETRIES} retries) and aborted`,
+        })
+      }
+
+      logger.debug(
+        `Sleeping for ${config.REST_TRANSPORT_MS_BETWEEN_RATE_LIMIT_RETRIES}ms before retrying`,
+      )
+      await sleep(config.REST_TRANSPORT_MS_BETWEEN_RATE_LIMIT_RETRIES)
+      response = await axios.request(axiosRequest)
+    }
+    return response
+  }
+
+  validateInputParams(params: AdapterInputParameters): string[] {
+    const encounteredIds: { [key: string]: number } = {}
+    const errors: string[] = []
+    const { ibanIDs } = params
+
+    ibanIDs.forEach((v) => {
+      if (!v.match(ibanPattern)) {
+        errors.push(`Invalid IBAN: ${v}`)
+      }
+      encounteredIds[v] += 1
+      if (encounteredIds[v] > 1) {
+        errors.push(`The following IBAN appears more than once in the input parameters: ${v}`)
+      }
+    })
+    return errors
+  }
+
+  /**
+   * Fetches pages of data from the Bank Frick API, scans for accounts by IBAN, and returns the balance
+   * of all found accounts. Returns a 404 if any IBAN isn't found.
+   */
+  async setup(
+    req: AdapterRequest<AdapterInputParameters>,
+    config: AdapterConfig<typeof customSettings>,
+  ): Promise<AdapterResponse<number>> {
+    const { ibanIDs, signingAlgorithm } = req.requestContext.data
+    const { PAGE_SIZE = 500 } = config
+
+    logger.debug(`Validating input: ${JSON.stringify(req.requestContext.data)}`)
+
+    // Scan ibanIDs for duplicates and invalid IBANs
+    const validationErrors = this.validateInputParams(req.requestContext.data)
+    if (validationErrors.length > 0) {
+      throw new AdapterError({
+        statusCode: 420,
+        message: `Received the following errors when validating inputParameters:\n ${validationErrors.join(
+          '\n',
+        )}`,
+      })
+    }
+
+    // Refresh the token if it isn't set
+    if (!this.token) {
+      this.token = await generateJWT(config, signingAlgorithm)
+    }
+
+    let sum = 0
+    let position = 0
+    const keys = ibanIDs
+    logger.info("Fetching accounts from Bank Frick's API...")
+    while (keys.length > 0) {
+      // TODO Fetching and processing pages can be run concurrently
+      const axiosRequest = this.prepareRequest(position, req.requestContext.data, config)
+      const response = await this.makeRequest(axiosRequest, config, signingAlgorithm)
+
+      logger.debug(`Evaluating accounts from page ${position / PAGE_SIZE}`)
+      response.data.accounts.forEach((v: Account) => {
+        logger.trace(`Evaluating ${v.account} (iban: ${v.iban}, type: ${v.type})`)
+        const index = ibanIDs.indexOf(v.iban)
+        if (index > -1) {
+          keys.splice(index, 1)
+          sum += v.balance
+          logger.trace(`Found account: ${v.account} (iban: ${v.iban}) with balance of ${v.balance}`)
+          logger.trace(
+            `Running sum: ${sum}, number of ibans left to find: ${keys.length}/${ibanIDs.length}`,
+          )
+        }
+      })
+
+      if (!response.data.moreResults) {
+        logger.debug('No more results, breaking out of account query loop')
+        break
+      }
+      position += PAGE_SIZE || 0
+    }
+
+    // 404 if one or more accounts were not found
+    if (keys.length > 0) {
+      logger.error(`Could not find all accounts, returning 404: ${keys.join(', ')}`)
+      const res = {
+        data: 0,
+        statusCode: 404,
+        result: 0,
+      }
+      await this.cache.set(req.requestContext.cacheKey, res, config.CACHE_MAX_AGE)
+    }
+
+    logger.debug('Was able to find all accounts, returning balance across all accounts: ', sum)
+    const res = {
+      data: sum,
+      statusCode: 200,
+      result: sum,
+    }
+    await this.cache.set(req.requestContext.cacheKey, res, config.CACHE_MAX_AGE)
+    return res
+  }
+}
+
+export const accountsRestEndpoint: AdapterEndpoint = {
+  name: 'accounts',
+  transport: new BankFrickAccountsTransport(),
+  inputParameters,
+}

package/src/examples/bank-frick/config/index.ts

@@ -0,0 +1,53 @@
+import { SettingsMap } from '../../../config'
+import crypto from 'crypto'
+import { SigningAlgorithm } from '../types'
+import { makeLogger } from '../../../util'
+
+const logger = makeLogger('BankFrickConfig')
+
+// Used for enum options and validation
+export const signingAlgorithms: SigningAlgorithm[] = ['rsa-sha256', 'rsa-sha384', 'rsa-sha512']
+const MAX_PAGE_SIZE = 500
+
+export const customSettings: SettingsMap = {
+  PAGE_SIZE: {
+    description: 'The number of accounts to fetch per call to /accounts. Must be >= 1 and <= 500.',
+    type: 'number',
+    required: false,
+    default: MAX_PAGE_SIZE,
+    validate: (value) => {
+      if (!value) {
+        return ''
+      } else if (value < 1) {
+        return `PAGE_SIZE must be at least >= 1, was ${value}`
+      } else if (value > MAX_PAGE_SIZE) {
+        return `PAGE_SIZE must be <= 500, was ${value}`
+      }
+    },
+  },
+  PRIVATE_KEY: {
+    description: '',
+    type: 'string',
+    required: true,
+    validate: (value) => {
+      const failedAlgos: SigningAlgorithm[] = []
+      for (const algorithm of signingAlgorithms) {
+        const body = { example: 123 }
+        try {
+          crypto.sign(algorithm, Buffer.from(JSON.stringify(body)), value)
+          logger.trace("Successfully tested PRIVATE_KEY by signing with algorithm '%s'", algorithm)
+        } catch {
+          logger.trace("PRIVATE_KEY failed to sign message with algorithm '%s'", algorithm)
+          failedAlgos.push(algorithm)
+        }
+      }
+
+      if (failedAlgos.length > 0) {
+        return `Failed to sign a dummy body using $PRIVATE_KEY with the following algorithms ${failedAlgos.join(
+          ',',
+        )}`
+      }
+      logger.debug('$PRIVATE_KEY successfully signed a dummy body with all supported algorithms')
+    },
+  },
+} as const

package/src/examples/bank-frick/index.ts

@@ -0,0 +1,13 @@
+import { Adapter } from '../../adapter'
+import { accountsRestEndpoint } from './accounts'
+import { customSettings } from './config'
+
+export const adapter: Adapter = {
+  name: 'bank-frick',
+  defaultEndpoint: 'accounts',
+  endpoints: [accountsRestEndpoint],
+  customSettings,
+  envDefaultOverrides: {
+    API_ENDPOINT: 'https://olbsandbox.bankfrick.li/webapi/v2',
+  },
+}

package/src/examples/bank-frick/types.d.ts

@@ -0,0 +1,38 @@
+export interface Account {
+  account: string // The account number of the account
+  type: string // The type of the account
+  iban: string // The iban of the account if exists
+  customer: string // The customer data of the account which consists of the customer number and name
+  currency: string // The account currency
+  balance: number // The current account balance
+  available: number // The available amount of the account as defined in the online banking
+}
+/**
+ * Types representing what we send/receive from the bank frick api
+ * See https://developers.bankfrick.li/docs#data-types for details
+ */
+export interface BankFrickAccountsResponseSchema {
+  errors?: string[]
+  date: Date
+  moreResults: boolean
+  resultSetSize: number
+  accounts: Account[]
+}
+export interface BankFrickAccountsRequestSchema {
+  firstPosition: number
+  maxResults: number
+}
+
+/**
+ * Types representing the input parameters and response of the adapter
+ */
+export interface AdapterInputParameters {
+  ibanIDs: string[]
+  signingAlgorithm?: SigningAlgorithm
+}
+
+/**
+ * These are the options from the docs, but it's hard to see. See the first paragraph from this
+ * page for details:  https://developers.bankfrick.li/docs#getting-started-signatures
+ */
+export type SigningAlgorithm = 'dsa-sha512' | 'rsa-sha256' | 'rsa-sha384' | 'rsa-sha512'

package/src/examples/bank-frick/util.ts

@@ -0,0 +1,55 @@
+import crypto from 'crypto'
+import { SigningAlgorithm } from './types'
+import { customSettings } from './config'
+import axios, { AxiosRequestConfig } from 'axios'
+import { makeLogger } from '../../util'
+import { AdapterConfig } from '../../config'
+
+interface TokenResponseBody {
+  errors?: string[]
+  token: string
+}
+interface TokenRequestBody {
+  key: string
+}
+
+const logger = makeLogger('BankFrickUtil')
+
+// Used by all endpoints requiring authentication
+export const generateJWT = async (
+  config: AdapterConfig<typeof customSettings>,
+  signingAlgorithm: SigningAlgorithm = 'rsa-sha512',
+): Promise<string> => {
+  logger.info("Generating a new JWT because we don't have one in config.token")
+  const { API_KEY, PRIVATE_KEY, API_ENDPOINT } = config
+
+  // All of these are required, so validation should have failed prior to this line
+  if (!API_KEY || !PRIVATE_KEY) {
+    throw new Error(
+      'API_KEY, PRIVATE_KEY, and PASSWORD all must be defined to get a new token\n' +
+        'Received:  \n' +
+        `API_KEY: ${API_KEY}\n` +
+        `PRIVATE_KEY: ${PRIVATE_KEY}`,
+    )
+  }
+
+  const data: TokenRequestBody = {
+    key: API_KEY,
+  }
+
+  const signature = crypto.sign(signingAlgorithm, Buffer.from(JSON.stringify(data)), PRIVATE_KEY)
+  const options: AxiosRequestConfig<TokenRequestBody> = {
+    method: 'POST',
+    baseURL: API_ENDPOINT,
+    url: `authorize`,
+    headers: {
+      Signature: signature.toString('base64'),
+      algorithm: signingAlgorithm,
+    },
+    data,
+  }
+
+  const response = await axios.request<TokenResponseBody>(options)
+
+  return response.data.token
+}

package/src/examples/coingecko/src/config/index.ts

@@ -0,0 +1,12 @@
+export const NAME = 'COINGECKO'
+
+export const DEFAULT_ENDPOINT = 'crypto'
+export const DEFAULT_API_ENDPOINT = 'https://api.coingecko.com/api/v3'
+export const PRO_API_ENDPOINT = 'https://pro-api.coingecko.com/api/v3'
+
+export const customSettings = {
+  API_KEY: {
+    description: 'API key for the CoinGecko API',
+    type: 'string',
+  },
+} as const