@mfxhub/sdk 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,30 @@ Every release of `@mfxhub/sdk`, newest first. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
 [Semantic Versioning](https://semver.org/).
 
+## 0.4.0
+
+### Added
+
+- Trade a trading account on any venue: `client.tradingAccounts.placeOrder`, `cancelOrder`,
+  `modifyOrder`, `modifyPosition`, `closePosition`, `closePositionBy`, `closePositionPartial`,
+  `setTrailingStop` and `clearTrailingStop` take the account's id and send to
+  `/v1/accounts/{id}/...` (scope `exec:write`). Same bodies and rules as `client.execution`: a
+  required `idempotencyKey`, a result resolved and never rejected, nothing retried. Read the
+  outcome with `client.execution.waitFor`.
+- Read a trading account on any venue: `funds`, `positions`, `pendingOrders`, `dealsPage` and
+  `deals` (with `position` to read one position's deals) and `symbols` (scope `acct:read`).
+  `symbols` gives a cTrader account's volume rules in lots and its leverage.
+- Connect cTrader accounts: `startCtraderGrant({ environment, scope, returnUrl })` resolves to the
+  consent link to send the trader to; `ctraderGrant(id)` lists the accounts they shared;
+  `connectCtraderAccounts(id, [...])` makes the chosen ones trading accounts of yours;
+  `revokeCtraderGrant(id)` moves them to `REAUTH_NEEDED`.
+- `ExecutionResult` reads what a venue adds: `venue`, `venueCode` (the venue's own refusal code
+  beside `reason`), `deals` (each a `VenueDeal` with `volumeUnits` and `price`), `volumeUnits`,
+  `closeByEmulated` and `protectionNotSet`.
+- The reasons `venue_unavailable` (retryable) and `not_on_this_venue`.
+- `new Execution(client, "accounts")` sends to a trading account's routes; the default is a
+  terminal's, as before.
+
 ## 0.3.0
 
 ### Added

package/dist/accounts.d.ts

@@ -30,7 +30,11 @@ export interface DealPageOptions extends DealWindow {
 /** Read the trading account behind a terminal: figures, positions, pending orders and deals. */
 export declare class Accounts {
     #private;
-    constructor(client: MfxClient);
+    /**
+     * `resource` is whose account is read: a terminal's (`client.accounts`) or a trading
+     * account's on any venue (`client.tradingAccounts`), which answer the same shapes.
+     */
+    constructor(client: MfxClient, resource?: "terminals" | "accounts");
     /** The account's figures. Another tenant's terminal is not found. */
     account(terminalId: string): Promise<Account>;
     /** Every open position, as one snapshot with its `as_of`. */

package/dist/accounts.js

@@ -18,27 +18,35 @@ function instant(name, value) {
 /** Read the trading account behind a terminal: figures, positions, pending orders and deals. */
 export class Accounts {
     #client;
-    constructor(client) {
+    #resource;
+    #idName;
+    /**
+     * `resource` is whose account is read: a terminal's (`client.accounts`) or a trading
+     * account's on any venue (`client.tradingAccounts`), which answer the same shapes.
+     */
+    constructor(client, resource = "terminals") {
         this.#client = client;
+        this.#resource = resource;
+        this.#idName = resource === "accounts" ? "accountId" : "terminalId";
     }
     /** The account's figures. Another tenant's terminal is not found. */
     async account(terminalId) {
-        const id = uuid("terminalId", terminalId);
+        const id = uuid(this.#idName, terminalId);
         return (await this.#client.read({
             method: "GET",
-            path: `/terminals/${id}/account`,
+            path: `/${this.#resource}/${id}/account`,
         }));
     }
     /** Every open position, as one snapshot with its `as_of`. */
     async positions(terminalId) {
-        const id = uuid("terminalId", terminalId);
-        const path = `/terminals/${id}/positions`;
+        const id = uuid(this.#idName, terminalId);
+        const path = `/${this.#resource}/${id}/positions`;
         return (await this.#client.read({ method: "GET", path }));
     }
     /** Every pending order, as one snapshot with its `as_of`. */
     async pendingOrders(terminalId) {
-        const id = uuid("terminalId", terminalId);
-        const path = `/terminals/${id}/orders/pending`;
+        const id = uuid(this.#idName, terminalId);
+        const path = `/${this.#resource}/${id}/orders/pending`;
         return (await this.#client.read({ method: "GET", path }));
     }
     /**
@@ -46,7 +54,7 @@ export class Accounts {
      * and so by this: an unbounded history read is the query that takes a database down.
      */
     async dealsPage(terminalId, options) {
-        const id = uuid("terminalId", terminalId);
+        const id = uuid(this.#idName, terminalId);
         const from = instant("from", options.from);
         const to = instant("to", options.to);
         if (options.to.getTime() < options.from.getTime()) {
@@ -61,7 +69,7 @@ export class Accounts {
         }
         const body = await this.#client.read({
             method: "GET",
-            path: `/terminals/${id}/history/deals`,
+            path: `/${this.#resource}/${id}/history/deals`,
             query: {
                 from,
                 to,

package/dist/execution.d.ts

@@ -84,10 +84,16 @@ export interface WaitFor {
 export declare const POLL_FROM_MS = 200;
 /** The longest pause between two reads of a command. */
 export declare const POLL_CAP_MS = 2000;
+/** Where a command goes: a terminal's routes, or a trading account's on any venue. */
+export type Resource = "terminals" | "accounts";
 /** Order entry for one tenant. Every method resolves to a result; none rejects. */
 export declare class Execution {
     #private;
-    constructor(client: MfxClient);
+    /**
+     * `resource` is where the commands go: a terminal's routes (`client.execution`) or a trading
+     * account's (`client.tradingAccounts`), which take the same bodies under the same rules.
+     */
+    constructor(client: MfxClient, resource?: Resource);
     /**
      * Place a market or pending order. Resolves once the platform has persisted the command
      * (state ACCEPTED, with its `commandId`); the outcome follows on the stream.

package/dist/execution.js

@@ -93,8 +93,14 @@ function closing(options) {
 /** Order entry for one tenant. Every method resolves to a result; none rejects. */
 export class Execution {
     #client;
-    constructor(client) {
+    #resource;
+    /**
+     * `resource` is where the commands go: a terminal's routes (`client.execution`) or a trading
+     * account's (`client.tradingAccounts`), which take the same bodies under the same rules.
+     */
+    constructor(client, resource = "terminals") {
         this.#client = client;
+        this.#resource = resource;
     }
     /**
      * Place a market or pending order. Resolves once the platform has persisted the command
@@ -104,10 +110,10 @@ export class Execution {
      * belongs, a missing idempotency key, a comment over 31 characters.
      */
     async placeOrder(terminalId, order) {
-        const id = uuid("terminalId", terminalId);
+        const id = uuid(this.#idName, terminalId);
         const key = idempotencyKey(order.idempotencyKey);
         const body = orderBody(order);
-        return this.#command({ method: "POST", path: `/terminals/${id}/orders`, body, idempotencyKey: key }, key);
+        return this.#command({ method: "POST", path: `/${this.#resource}/${id}/orders`, body, idempotencyKey: key }, key);
     }
     /**
      * Amend a pending order's price, stops or expiry; at least one must change. Its volume, side,
@@ -196,12 +202,16 @@ export class Execution {
         }
         return result;
     }
+    /** The name a wrong id is reported under. */
+    get #idName() {
+        return this.#resource === "accounts" ? "accountId" : "terminalId";
+    }
     /** One command on an existing order or position: checked, then sent once. */
     async #on(terminalId, ticket, kind, action, options, body, method = "POST") {
-        const id = uuid("terminalId", terminalId);
+        const id = uuid(this.#idName, terminalId);
         const number = ticketOf("ticket", ticket);
         const key = idempotencyKey(options?.idempotencyKey);
-        const path = `/terminals/${id}/${kind}/${String(number)}/${action}`;
+        const path = `/${this.#resource}/${id}/${kind}/${String(number)}/${action}`;
         return this.#command({ method, path, ...(body === undefined ? {} : { body }), idempotencyKey: key }, key);
     }
     /**