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'asyncfunctionsomeBrokerizeActions(){constbrokerize=newBrokerize({/* 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)=>{returnfetch(url,init)})asany,createAbortController: ()=>newAbortController(),createWebSocket: (url,protocol)=>newWebSocket(url,protocol),// basePath: 'https://api-preview.brokerize.com', // this is the default value// basePathCryptoService: 'https://crypto-service-api.com' // the optional external crypto service// acceptLanguage: 'de', // optional `Accept-Language` header for localized responses (e.g. legal terms).// // may also be a function `() => 'de'` that is evaluated on every request,// // so runtime language changes are picked up without recreating the client.})/* create a guest user. the result contains the user's tokens and be stored, e.g. in a cookie or session storage */constguestUserAuthContextConfiguration=awaitbrokerize.createGuestUser()consttokenRefreshCallback=(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.*/constctx=brokerize.createAuthorizedContext(guestUserAuthContextConfiguration,tokenRefreshCallback);/* do some API calls */console.log('BROKERS',awaitctx.getBrokers())console.log('EXCHANGES',awaitctx.getExchanges())const{ id }=awaitctx.createDemoAccount()constdemoAccounts=awaitctx.getDemoAccounts()constdemoAccount=demoAccounts.accounts.find(x=>x.accountId==id)constsession=awaitctx.addSession({brokerName: BrokerName.Demo,env: 'test',password: '42',username: demoAccount.accountName})/* subscribe to some non-existent decoupled operation */constclient=ctx.createWebSocketClient()consts=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:

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