The official brokerize
JavaScript client. The main goal here is to have an API client that 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.
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. */
fetch: ((url, init) => {
return fetch(url, init)
}) as any,
createAbortController: () => new AbortController(),
createWebSocket: (url, protocol) => new WebSocket(url, protocol)
})
/* 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)
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.
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 */,
},
});