client-js

The official brokerize JavaScript client. The API client comes with TypeScript types so that auto-complete for JS code as well as proper types for TypeScript clients are available. Most of the heavy lifting is in the internal generated code (we use @openapitools/openapi-generator-cli to generate it), but we provide a manually maintained layer around it for a more consistent developer experience.

Example usage:

import { Brokerize, BrokerName } from '@brokerize/client'

async function someBrokerizeActions() {
  const brokerize = new Brokerize({
    /* provide implementations of fetch, AbortController and WebSocket that will
       be used for interacting with the API. If you leave out those dependencies, they will default to globally available
       implementations, which should usually work in browsers and newer Node.JS environments, but may fail in other JS environments
       that do not provide them (e.g. runtimes in mobile apps). */
    fetch: ((url, init) => {
      return fetch(url, init)
    }) as any,
    createAbortController: () => new AbortController(),
    createWebSocket: (url, protocol) => new WebSocket(url, protocol),
    // basePath: 'https://api-preview.brokerize.com', // this is the default value
    // basePathCryptoService: 'https://crypto-service-api.com' // the optional external crypto service
  })

  /* create a guest user. the result contains the user's tokens and be stored, e.g. in a cookie or session storage */
  const guestUserAuthContextConfiguration = await brokerize.createGuestUser()

  const tokenRefreshCallback = (updatedAuthCtx) => {
    /* this callback gets called when the token set gets updated and allows you to store it */
  };

  /* with the guest user's token, create an authorized context.*/
  const ctx = brokerize.createAuthorizedContext(guestUserAuthContextConfiguration, tokenRefreshCallback);

  /* do some API calls */
  console.log('BROKERS', await ctx.getBrokers())
  console.log('EXCHANGES', await ctx.getExchanges())
  const { id } = await ctx.createDemoAccount()
  const demoAccounts = await ctx.getDemoAccounts()
  const demoAccount = demoAccounts.accounts.find(x => x.accountId == id)

  const session = await ctx.addSession({
    brokerName: BrokerName.Demo,
    env: 'test',
    password: '42',
    username: demoAccount.accountName
  })

  /* subscribe to some non-existent decoupled operation */
  const client = ctx.createWebSocketClient()
  const s = client.subscribeDecoupledOperation({
    decoupledOperationId: 'X',
    sessionId: 'XXXX'
  }, (err, data) => {
    console.log('SUBSCR')
  })
  s.unsubscribe();
  console.log('SESSION', session)
}
someBrokerizeActions().then(console.log, console.error)

development & maintenance

The code in src/swagger is generated by the npm script npm run generate from the OpenAPI spec and will be regenerated whenever API changes are made. No manual changes should be made in the src/swagger directory. npm run download-spec will download the current spec from api-preview.brokerize.com.

The following manual steps have to be performed when updating the API:

• src/webSocketTypes.ts is a copy from the backend webSocketTypes.ts and must be kept in sync manually for the time being.
• src/modelExports.ts is a manual selection of the types as generated by openapi-generator (it generates a few types and internal JSON conversion helpers that do not need to be exported). Have a look at the diff of src/swagger/models/index.ts to see which changes should me made.

npm run build lets api-extractor generate a new API report.

working with registered brokerize users

brokerize uses AWS Cognito for user authentication. If clients want brokerize users to log in with their brokerize credentials, they can use the libraries provided by AWS to do so. If you use our component-based solution @brokerize/elements, a wrapper is provided there.

BrokerizeConfig needs to be provided with the cognito configuration, including a CognitoFacade which is responsible for getting the current idToken to use for API calls:

const brokerize = new Brokerize({
  // see above:
  fetch,
  createAbortController,
  createWebSocket,
  cognito: {
    poolConfig /* client and user pool config options */,
    cognitoFacade /* a small wrapper interface for retrieving the token */,
  },
});