@mfxhub/sdk 0.2.3 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,72 @@ 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
+
+- A terminal can be `QUEUED`: placed on a cell and waiting for its turn to start. A cell starts
+  terminals a few at a time so the ones already running are not slowed. `terminal.queue` says its
+  place, when it is expected to start (`expected_start_at`) and why it waits (a coarse `reason`).
+  `isUsable` is false for it, as for every state but ACTIVE.
+- `terminals.waitUntilActive(id, { timeoutMs })`: reads the terminal until it is no longer on its
+  way to ACTIVE. A QUEUED terminal is read again at its expected start (2 s to 1 min away), not on
+  a fixed beat.
+- `terminals.bulkRestart` and `terminals.bulkRetire` (`POST /v1/terminals:restart`,
+  `POST /v1/terminals:retire`): many terminals by farm, broker or ids, answered at once with the
+  action, what was refused and the expected finish. `getBulkAction` and `cancelBulkAction` follow
+  and cancel it.
+
+### Changed
+
+- The vendored API description is the platform's current public contract, with the queued state,
+  the queue fields and the bulk routes; the generated types follow it.
+
+### Fixed
+
+- A request path whose first segment holds a colon (`/terminals:restart`) is sent to the API. The
+  URL parser read `terminals:` as a scheme.
+
+## 0.2.4
+
+### Added
+
+- `client.tradingAccounts`: the trading accounts over every venue (`GET /v1/accounts`,
+  `GET /v1/accounts/{id}`, scope `acct:read`). `page()` and `list()` narrow by `venue`,
+  `environment` and `state` on the platform; `get(id)` takes the account's id or one of its
+  terminals' ids. An MT5 account's id is its terminal's id. The state is the venue-neutral word
+  (`CONNECTED`, `DEGRADED`, `REAUTH_NEEDED`, ...). `client.accounts` is unchanged: it is still the
+  balance, positions and deals of a terminal's account.
+
+### Changed
+
+- The vendored API description is the platform's current public contract, and the generated types
+  follow it.
+
 ## 0.2.3
 
 ### 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/client.d.ts

@@ -5,6 +5,7 @@ import { Catalog } from "./catalog.js";
 import { Execution } from "./execution.js";
 import { MfxStream, type StreamOptions } from "./stream.js";
 import { Terminals } from "./terminals.js";
+import { TradingAccounts } from "./trading-accounts.js";
 /** Default time a single request may take. */
 export declare const DEFAULT_TIMEOUT_MS = 30000;
 /** How many times a rate-limited read is tried again. */
@@ -73,6 +74,8 @@ export declare class MfxClient {
     readonly catalog: Catalog;
     /** The trading account behind a terminal: figures, positions, pending orders and deals. */
     readonly accounts: Accounts;
+    /** The trading accounts over every venue: an MT5 account, and later a cTrader one. */
+    readonly tradingAccounts: TradingAccounts;
     /**
      * @param baseUrl the API's base, including the version: `https://api.mfxhub.com/v1`, or
      *   `https://api.dev.mfxhub.com/v1` for development

package/dist/client.js

@@ -13,6 +13,7 @@ import { Catalog } from "./catalog.js";
 import { Execution } from "./execution.js";
 import { MfxStream } from "./stream.js";
 import { Terminals } from "./terminals.js";
+import { TradingAccounts } from "./trading-accounts.js";
 import { USER_AGENT } from "./version.js";
 /** Default time a single request may take. */
 export const DEFAULT_TIMEOUT_MS = 30_000;
@@ -55,6 +56,8 @@ export class MfxClient {
     catalog;
     /** The trading account behind a terminal: figures, positions, pending orders and deals. */
     accounts;
+    /** The trading accounts over every venue: an MT5 account, and later a cTrader one. */
+    tradingAccounts;
     /**
      * @param baseUrl the API's base, including the version: `https://api.mfxhub.com/v1`, or
      *   `https://api.dev.mfxhub.com/v1` for development
@@ -76,6 +79,7 @@ export class MfxClient {
         this.execution = new Execution(this);
         this.catalog = new Catalog(this);
         this.accounts = new Accounts(this);
+        this.tradingAccounts = new TradingAccounts(this);
     }
     /** The id of the key this client signs with. Safe to log, unlike the private key. */
     get keyId() {
@@ -133,7 +137,9 @@ export class MfxClient {
     }
     /** One attempt, signed afresh. Transport faults become MfxTransportError or MfxTimeout. */
     async send(spec) {
-        const url = new URL(spec.path.replace(/^\//, ""), this.#base);
+        // "./" keeps a path with a colon in its first segment (`/terminals:restart`) relative: without
+        // it the URL parser reads `terminals:` as a scheme and the request leaves the API.
+        const url = new URL("./" + spec.path.replace(/^\/+/, ""), this.#base);
         for (const [name, value] of Object.entries(spec.query ?? {})) {
             if (value === null || value === undefined)
                 continue;

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);
     }
     /**