@brokerize/client 1.0.1

package/README.md

@@ -0,0 +1,89 @@
+# client-js
+
+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:
+
+```javascript
+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)
+```
+
+# 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:
+
+```typescript
+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 */,
+  },
+});
+```

package/dist/apiCtx.d.ts

@@ -0,0 +1,71 @@
+import { Models, TokenRefreshCallback } from ".";
+import { WhatWgFetch } from "./dependencyDefinitions/fetch";
+import { WebSocket } from "./dependencyDefinitions/webSocket";
+import { Configuration } from "./swagger";
+export interface BrokerizeConfig {
+    fetch?: WhatWgFetch;
+    createAbortController?: () => AbortController;
+    createWebSocket?: (url?: string, protocol?: string | string[]) => WebSocket;
+    /**
+     * Path to the API, e.g. https://api-preview.brokerize.com
+     */
+    basePath?: string;
+    clientId: string;
+    /**
+     * The AWS cognito configuration, if the application is supposed to be used with brokerize accounts.
+     */
+    cognito?: CognitoConfig;
+}
+export type AuthContextConfiguration = GuestAuthContextConfiguration | RegisteredUserAuthContextConfiguration;
+export type RegisteredUserAuthContextConfiguration = {
+    type: "registered";
+    username: string;
+    tokens: TokenSet;
+};
+export type TokenSet = {
+    idToken: string;
+    refreshToken: string;
+    expiresAt: number;
+};
+export interface GuestAuthContextConfiguration {
+    type: "guest";
+    /**
+     * @deprecated use tokens instead
+     */
+    idToken: string;
+    tokens: {
+        updatedAt: number;
+        response: Models.CreateGuestUserResponse;
+    };
+}
+export interface Auth {
+    getToken: () => Promise<{
+        idToken: string;
+    }>;
+}
+export declare function createConfiguration(cfg: BrokerizeConfig): Configuration;
+export declare function createAuth({ authCfg, cfg, options, tokenRefreshCallback, }: {
+    authCfg: AuthContextConfiguration;
+    cfg: BrokerizeConfig;
+    options?: AuthorizedApiContextOptions;
+    tokenRefreshCallback?: TokenRefreshCallback;
+}): Auth;
+export type CognitoConfig = {
+    poolConfig: CognitoPoolConfig;
+    cognitoFacade: CognitoFacade;
+};
+export type CognitoPoolConfig = {
+    UserPoolId: string;
+    ClientId: string;
+    Endpoint?: string | null;
+};
+export type CognitoFacade = {
+    createSession: (cognitoPoolConfig: CognitoPoolConfig, authCfg: RegisteredUserAuthContextConfiguration) => {
+        getToken: () => Promise<{
+            idToken: string;
+        }>;
+    };
+};
+export type AuthorizedApiContextOptions = {
+    cognitoFacade?: CognitoFacade;
+};

package/dist/apiCtx.js

@@ -0,0 +1,86 @@
+/* Import/Export the DOM parts we rely on. Those are partial copies from the official TypeScript DOM library definitions (https://github.com/microsoft/TypeScript/blob/master/lib/lib.dom.d.ts),
+   but reduced to the parts actually used by bg-trading. */
+import { BrokerizeError } from ".";
+import { Configuration } from "./swagger";
+export function createConfiguration(cfg) {
+    if (!cfg.clientId) {
+        throw new Error("You must configure a clientId to use the brokerize API.");
+    }
+    return new Configuration({
+        fetchApi: cfg.fetch,
+        basePath: cfg.basePath,
+    });
+}
+export function createAuth({ authCfg, cfg, options, tokenRefreshCallback, }) {
+    var _a;
+    if (authCfg.type == "guest") {
+        const guestAuthCfg = JSON.parse(JSON.stringify(authCfg)); // clone it
+        return {
+            async getToken() {
+                if (guestAuthCfg.tokens) {
+                    /* modern tokens */
+                    const tokenExpiresAt = guestAuthCfg.tokens.updatedAt +
+                        guestAuthCfg.tokens.response.expiresIn * 1000 -
+                        10000;
+                    const needsRefresh = Date.now() > tokenExpiresAt;
+                    if (needsRefresh && guestAuthCfg.tokens.response.refreshToken) {
+                        if (!cfg.fetch) {
+                            throw new Error("Invalid cfg: fetch is required for refreshing tokens.");
+                        }
+                        const response = await fetch(cfg.basePath + "/user/token", {
+                            method: "POST",
+                            headers: {
+                                "x-brkrz-client-id": cfg.clientId,
+                                "Content-Type": "application/x-www-form-urlencoded",
+                            },
+                            // XXX some runtimes do not have URLSearchParams, so just produce the body in the old-fashioned way
+                            body: `grant_type=refresh_token&refresh_token=${encodeURIComponent(guestAuthCfg.tokens.response.refreshToken)}`,
+                        });
+                        if (!response.ok) {
+                            throw new BrokerizeError(401, {
+                                msg: "The token could not be refreshed. Please log in again.",
+                                code: "AUTH",
+                            });
+                        }
+                        const responseJson = (await response.json());
+                        guestAuthCfg.idToken = responseJson.access_token;
+                        // replace the original object
+                        guestAuthCfg.tokens = {
+                            updatedAt: Date.now(),
+                            response: {
+                                accessToken: responseJson.access_token,
+                                refreshToken: responseJson.refresh_token,
+                                expiresIn: responseJson.expires_in,
+                                tokenType: responseJson.token_type,
+                                refreshTokenExpiresIn: responseJson.refresh_token_expires_in,
+                                idToken: responseJson.access_token,
+                            },
+                        };
+                        if (tokenRefreshCallback) {
+                            tokenRefreshCallback(guestAuthCfg);
+                        }
+                        return { idToken: responseJson.access_token };
+                    }
+                }
+                return { idToken: guestAuthCfg.idToken };
+            },
+        };
+    }
+    else if (authCfg.type == "registered") {
+        if (!cfg.cognito) {
+            throw new Error("Trying to initialize createAuth for cognito, but no cognito config present in BrokerizeConfig.");
+        }
+        if (!(options === null || options === void 0 ? void 0 : options.cognitoFacade)) {
+            throw new Error("Trying to initialize createAuth for cognito, but access to the cognito library was not provided in the options.");
+        }
+        const session = options.cognitoFacade.createSession((_a = cfg.cognito) === null || _a === void 0 ? void 0 : _a.poolConfig, authCfg);
+        return {
+            async getToken() {
+                return session.getToken();
+            },
+        };
+    }
+    else {
+        throw new Error("Unsupported auth config.");
+    }
+}

package/dist/authorizedApiContext.d.ts

@@ -0,0 +1,137 @@
+import { Auth, BrokerizeConfig } from "./apiCtx";
+import * as openApiClient from "./swagger";
+import { AddSessionParams, ConfirmOAuthParams, CreateTradeChallengeRequest, CreateTradeRequest, DeleteDemoAccountRequest, DemoAccountSettings, GenericTable, GetCostEstimationParams, GetQuoteRequest, OrderChanges, PrepareOAuthRedirectParams, PrepareTradeRequest } from "./swagger";
+import { BrokerizeWebSocketClient, BrokerizeWebSocketClientImpl, Callback, Subscription } from "./websocketClient";
+export declare class AuthorizedApiContext {
+    private _cfg;
+    private _auth;
+    private _defaultApi;
+    private _demoBrokerApi;
+    private _tradeApi;
+    private _isDestroyed;
+    private _abortController;
+    private _metaApi;
+    private _brokerLoginApi;
+    private _tradeDraftApi;
+    private _cancelOrderApi;
+    private _changeOrderApi;
+    private _logoutSubject;
+    private _childContexts;
+    private _wsClient;
+    private _cache;
+    private _exportApi;
+    private _adminApi;
+    private _userApi;
+    private _securitiesApi;
+    constructor(cfg: BrokerizeConfig, auth: Auth, wsClient?: BrokerizeWebSocketClientImpl);
+    createChildContext(): AuthorizedApiContext;
+    private _initRequestInit;
+    getBrokers(): Promise<openApiClient.GetBrokersResponse>;
+    getTradeDrafts(params: openApiClient.GetTradeDraftsRequest): Promise<openApiClient.GetActiveTradeDraftsResponse>;
+    createTradeDraft(params: openApiClient.CreateTradeDraftsRequest): Promise<openApiClient.CreateTradeDrafts200Response>;
+    updateTradeDraft(params: openApiClient.UpdateTradeDraftRequest): Promise<void>;
+    deactivateTradeDraft(params: openApiClient.DeactivateTradeDraftRequest): Promise<void>;
+    deleteTradeDraft(params: openApiClient.DeleteTradeDraftRequest): Promise<void>;
+    getLegalTerms(): Promise<openApiClient.LegalTermsResponse>;
+    getExchanges(): Promise<openApiClient.ExchangesResponse>;
+    addSession(params: AddSessionParams): Promise<openApiClient.LoginResponse>;
+    getSessions(): Promise<openApiClient.SessionResponse>;
+    createDemoAccount(demoAccountSettings?: DemoAccountSettings): Promise<openApiClient.CreatedResponseBody>;
+    getAccessTokens(): Promise<openApiClient.GetAccessTokensResponse>;
+    createAccessToken(params: openApiClient.CreateAccessTokenParams): Promise<openApiClient.AccessTokenResult>;
+    revokeAccessToken(accessTokenId: string): Promise<void>;
+    getAcessTokenAvailablePermissions(): Promise<openApiClient.GetAcessTokenAvailablePermissions200Response>;
+    getDemoAccounts(): Promise<openApiClient.DemoAccountsResponse>;
+    deleteDemoAccount(del: DeleteDemoAccountRequest): Promise<openApiClient.OkResponseBody>;
+    getOrder(orderId: string): Promise<openApiClient.GetOrderResponse>;
+    createCancelOrderChallenge(req: openApiClient.CreateCancelOrderChallengeRequest): Promise<openApiClient.Challenge>;
+    cancelOrder(req: openApiClient.CancelOrderRequest): Promise<void>;
+    createChangeOrderChallenge(req: openApiClient.CreateChangeOrderChallengeRequest): Promise<openApiClient.Challenge>;
+    changeOrder(req: openApiClient.ChangeOrderRequest): Promise<void>;
+    getPortfolios(): Promise<openApiClient.PortfoliosResponse>;
+    renamePortfolio(portfolioId: string, newPortfolioName: string): Promise<void>;
+    deletePortfolio(portfolioId: string): Promise<openApiClient.OkResponseBody>;
+    getPortfolioQuotes(portfolioId: string): Promise<openApiClient.GetPortfolioQuotesResponse>;
+    getPortfolioPositions(portfolioId: string): Promise<openApiClient.GetPortfolioPositionsResponse>;
+    getPortfolioOrders(req: openApiClient.GetPortfolioOrdersRequest): Promise<openApiClient.GetPortfolioOrdersResponse>;
+    getAuthInfo(portfolioId: string): Promise<openApiClient.GetAuthInfoResponse>;
+    addSessionCompleteChallenge(req: openApiClient.AddSessionCompleteChallengeRequest): Promise<openApiClient.LoginResponseReady>;
+    createSessionTanChallenge(req: openApiClient.CreateSessionTanChallengeRequest): Promise<openApiClient.Challenge>;
+    enableSessionTan(req: openApiClient.EnableSessionTanRequest): Promise<openApiClient.EnableSessionTanResponse>;
+    endSessionTan(sessionId: string): Promise<openApiClient.EndSessionTanResponse>;
+    getDecoupledOperationStatus(req: openApiClient.GetDecoupledOperationStatusRequest): Promise<openApiClient.DecoupledOperationStatus>;
+    cancelDecoupledOperation(req: openApiClient.CancelDecoupledOperationRequest): Promise<void>;
+    triggerSessionSync(sessionId: string): Promise<openApiClient.OkResponseBody>;
+    triggerDemoSessionSyncError(sessionId: string): Promise<openApiClient.OkResponseBody>;
+    logoutSession(sessionId: string): Promise<openApiClient.OkResponseBody>;
+    getUser(): Promise<openApiClient.GetUserResponse>;
+    deleteGuestUser(): Promise<void>;
+    prepareTrade(req: PrepareTradeRequest): Promise<openApiClient.PrepareTradeResponse>;
+    createTrade(req: CreateTradeRequest): Promise<openApiClient.CreateTradeResponse>;
+    createTradeChallenge(req: CreateTradeChallengeRequest): Promise<openApiClient.Challenge>;
+    getCostEstimation(p: GetCostEstimationParams): Promise<openApiClient.OrderCostEstimation>;
+    getChangeOrderCostEstimation(orderId: string, changes: OrderChanges): Promise<openApiClient.OrderCostEstimation>;
+    getQuote(p: GetQuoteRequest): Promise<openApiClient.GetQuoteResponse>;
+    prepareOAuthRedirect(p: PrepareOAuthRedirectParams): Promise<openApiClient.PrepareOAuthRedirectResponse>;
+    confirmOAuth(p: ConfirmOAuthParams): Promise<openApiClient.ConfirmOAuthResponse>;
+    getSecurityDetailedInfo(token: string): Promise<openApiClient.GenericTable>;
+    renderGenericTablePdf(table: GenericTable): Promise<Blob>;
+    getMyClients(): Promise<openApiClient.ClientsResponseInner[]>;
+    createClient(): Promise<openApiClient.CreateClient200Response>;
+    deleteClient(clientId: string): Promise<void>;
+    addClientOrigin(clientId: string, origin: string): Promise<void>;
+    removeClientOrigin(clientId: string, origin: string): Promise<void>;
+    addClientOAuthReturnToUrl(clientId: string, url: string): Promise<void>;
+    removeClientOAuthReturnToUrl(clientId: string, url: string): Promise<void>;
+    setClientConfig(clientId: string, config: openApiClient.ClientConfigUpdate): Promise<void>;
+    getOrderReport(opts: {
+        from: string;
+        to: string;
+        clientIds?: string[];
+        onlyExecutedOrders?: boolean;
+        format?: "xlsx" | "csv";
+    }): Promise<{
+        filename: string | null;
+        data: Promise<Blob>;
+        contentType: string | null;
+    }>;
+    getSecurityQuotes(opts: {
+        securityQuotesToken: string;
+    }): Promise<openApiClient.SecurityQuotesResponse>;
+    getSecurityQuotesMeta(securityQuotesToken: string): Promise<openApiClient.SecurityQuotesMeta>;
+    /**
+     * Subscribe to security quotes. Note that this currently uses polling to load the quotes from the
+     * API. This will be replaced with a websocket-based solution in the future, but we can keep this
+     * interface upwards-compatible.
+     *
+     * If an error occurs during the polling, the callback will receive the error and the subscription
+     * ends, which means the application should handle the error and possibly re-subscribe later.
+     *
+     * @param securityQuotesToken the `securityQuotesToken` to subscribe to
+     * @param callback a callback that will be called with the quotes
+     * @returns a subscription object with a function `unsubscribe` that can be used to stop polling
+     */
+    subscribeQuotes(securityQuotesToken: string, callback: Callback<openApiClient.SecurityQuotesResponse | undefined>): {
+        unsubscribe(): void;
+    };
+    /**
+     * Subscribe to the available order intents based on a `PreparedTrade`. Note that this currently uses polling to load the quotes from the
+     * API. This will be replaced with a websocket-based solution in the future, but we can keep this
+     * interface upwards-compatible.
+     *
+     * If an error occurs during the polling, the callback will receive the error and the subscription
+     * ends, which means the application should handle the error and possibly re-subscribe later.
+     *
+     * @param preparedTrade The `PreparedTrade` as retrived by `PrepareTrade`.
+     * @param callback a callback that will be called with the available order intents
+     *
+     * @returns a subscription object with a function `unsubscribe` that can be used to stop polling
+     */
+    subscribeAvailableOrderIntents(preparedTrade: openApiClient.PreparedTrade, callback: Callback<openApiClient.OrderIntentAvailability | undefined>): {
+        unsubscribe(): void;
+    };
+    private _initInternalWebSocketClient;
+    createWebSocketClient(): BrokerizeWebSocketClient;
+    destroy(): void;
+    subscribeLogout(callback: Callback): Subscription;
+}