@mfxhub/sdk 0.2.2 → 0.3.0

package/dist/index.d.ts

@@ -6,8 +6,8 @@
  * const client = new MfxClient("https://api.dev.mfxhub.com/v1", keyId, privateKey);
  * ```
  */
-export { MfxClient, DEFAULT_READ_RETRIES, DEFAULT_TIMEOUT_MS } from "./client.js";
-export type { Answer, Budget, ClientOptions, RequestSpec } from "./client.js";
+export { MfxClient, CALL_LOG_ENV, DEFAULT_READ_RETRIES, DEFAULT_TIMEOUT_MS } from "./client.js";
+export type { Answer, Budget, CallTiming, ClientOptions, RequestSpec } from "./client.js";
 export * from "./errors.js";
 export { Page } from "./pages.js";
 export { Catalog } from "./catalog.js";
@@ -21,7 +21,9 @@ export type { Connector, StreamConnection, StreamEvent, StreamOptions, StreamSta
 export type { ClosePosition, ClosePositionBy, ClosePositionPartial, Keyed, ModifyOrder, ModifyPosition, OrderType, PlaceOrder, SetTrailingStop, Side, WaitFor, } from "./execution.js";
 export type { CommandState, ExecutionResult, Reason, Tickets } from "./results.js";
 export { Terminals, isUsable } from "./terminals.js";
-export type { CreateTerminal, JournalLine, JournalOptions, PageOptions, Redundancy, Terminal, TerminalFilter, TerminalJournal, TerminalState, } from "./terminals.js";
+export type { CreateTerminal, BulkAction, BulkAsk, JournalLine, JournalOptions, PageOptions, Redundancy, Terminal, TerminalFilter, TerminalJournal, TerminalQueue, TerminalState, WaitOptions, } from "./terminals.js";
+export { TradingAccounts } from "./trading-accounts.js";
+export type { AccountEnvironment, AccountState, TradingAccount, TradingAccountFilter, TradingAccountPageOptions, Venue, } from "./trading-accounts.js";
 export { RequestSigner, SigningKey, signingMessage } from "./signing.js";
 export { KEY_HEADER, NONCE_HEADER, SIGNATURE_HEADER, TIMESTAMP_HEADER } from "./signing.js";
 export type { components, operations, paths } from "./generated/api.js";

package/dist/index.js

@@ -6,7 +6,7 @@
  * const client = new MfxClient("https://api.dev.mfxhub.com/v1", keyId, privateKey);
  * ```
  */
-export { MfxClient, DEFAULT_READ_RETRIES, DEFAULT_TIMEOUT_MS } from "./client.js";
+export { MfxClient, CALL_LOG_ENV, DEFAULT_READ_RETRIES, DEFAULT_TIMEOUT_MS } from "./client.js";
 export * from "./errors.js";
 export { Page } from "./pages.js";
 export { Catalog } from "./catalog.js";
@@ -14,6 +14,7 @@ export { Accounts } from "./accounts.js";
 export { Execution, POLL_CAP_MS, POLL_FROM_MS } from "./execution.js";
 export { CLOSE_LIFETIME, CLOSE_REAUTHENTICATE, CLOSE_SLOW_CONSUMER, Channel, ChannelRefused, MfxStream, Resync, StreamClosed, StreamMessage, wsConnector, } from "./stream.js";
 export { Terminals, isUsable } from "./terminals.js";
+export { TradingAccounts } from "./trading-accounts.js";
 export { RequestSigner, SigningKey, signingMessage } from "./signing.js";
 export { KEY_HEADER, NONCE_HEADER, SIGNATURE_HEADER, TIMESTAMP_HEADER } from "./signing.js";
 export { VERSION } from "./version.js";

package/dist/terminals.d.ts

@@ -52,9 +52,31 @@ export interface PageOptions extends TerminalFilter {
 /**
  * Can this terminal be used right now: market data, execution, account reads? True only in ACTIVE.
  * OFFLINE means its cell is not reporting; the platform brings it back by itself, so retry rather
- * than create another.
+ * than create another. QUEUED means it is placed and waiting for its turn to start: its cell
+ * starts terminals a few at a time, and `queue.expected_start_at` says when to expect it.
  */
 export declare function isUsable(terminal: Pick<Terminal, "state">): boolean;
+/** Where a QUEUED terminal waits: its place, its expected start and why it waits. */
+export type TerminalQueue = components["schemas"]["TerminalQueue"];
+/** A bulk restart or retire: what was taken, what was refused, and its expected finish. */
+export type BulkAction = components["schemas"]["BulkAction"];
+/** What {@link Terminals.waitUntilActive} takes. */
+export interface WaitOptions {
+    /** How long to wait in all, in milliseconds. 15 minutes unless given. */
+    readonly timeoutMs?: number;
+}
+/** Which of your terminals a bulk action takes, and why. At least one filter. */
+export interface BulkAsk {
+    /** Why; written to the audit log and to each item. */
+    readonly reason: string;
+    /** Required: the same key sent again returns the same action. */
+    readonly idempotencyKey: string;
+    readonly farmId?: string;
+    readonly brokerId?: string;
+    readonly terminalIds?: readonly string[];
+    /** Without it, a terminal with open positions is refused and the rest are taken. */
+    readonly confirmOpenPositions?: boolean;
+}
 /** Provision and inspect the terminals this key's tenant owns. */
 export declare class Terminals {
     #private;
@@ -79,5 +101,30 @@ export declare class Terminals {
      * Sent once and never retried: if the answer is lost, send the same idempotency key again.
      */
     create(request: CreateTerminal): Promise<Terminal>;
+    /**
+     * Read the terminal until it is no longer on its way to ACTIVE (REQUESTED, QUEUED, PROVISIONING,
+     * LOGGING_IN), or until `timeoutMs` has been waited. Returns the last read either way: ACTIVE,
+     * a state it settled in instead (FAILED, for one), or still on its way when the time ran out.
+     *
+     * A QUEUED terminal is read again at its `queue.expected_start_at` (between 2 s and a minute
+     * away), not on a fixed beat: its cell starts terminals a few at a time, so asking every two
+     * seconds tells nothing new. Any other state is read again after 2 s, doubling to 15 s.
+     */
+    waitUntilActive(terminalId: string, options?: WaitOptions): Promise<Terminal>;
+    /**
+     * Restart many of your terminals at once. Each is judged by the rules of a single restart; a
+     * refused one is listed in `refused` with its rule's code and the rest are taken. Each cell
+     * carries its share at its own pace, so the terminals already running on it are not slowed.
+     * Answered at once with the action and its expected finish; its items never expire.
+     */
+    bulkRestart(ask: BulkAsk): Promise<BulkAction>;
+    /** Retire many of your terminals at once, as {@link bulkRestart} restarts them. */
+    bulkRetire(ask: BulkAsk): Promise<BulkAction>;
+    /** A bulk action's progress: counts per state, what was refused, and its expected finish. */
+    getBulkAction(bulkActionId: string): Promise<BulkAction>;
+    /** Cancel a bulk action: its waiting items are cancelled, running ones finish. */
+    cancelBulkAction(bulkActionId: string, options: {
+        readonly idempotencyKey: string;
+    }): Promise<BulkAction>;
 }
 export {};

package/dist/terminals.js

@@ -39,11 +39,53 @@ function stateQuery(state) {
 /**
  * Can this terminal be used right now: market data, execution, account reads? True only in ACTIVE.
  * OFFLINE means its cell is not reporting; the platform brings it back by itself, so retry rather
- * than create another.
+ * than create another. QUEUED means it is placed and waiting for its turn to start: its cell
+ * starts terminals a few at a time, and `queue.expected_start_at` says when to expect it.
  */
 export function isUsable(terminal) {
     return terminal.state === "ACTIVE";
 }
+/** The states a terminal passes through on its way to ACTIVE; every other state is settled. */
+const ON_ITS_WAY = new Set([
+    "REQUESTED",
+    "QUEUED",
+    "PROVISIONING",
+    "LOGGING_IN",
+]);
+const POLL_FROM_MS = 2_000;
+const POLL_CAP_MS = 15_000;
+/** A QUEUED terminal is read again at its expected start, but never less often than this. */
+const QUEUED_CAP_MS = 60_000;
+function bulkBody(ask) {
+    if (typeof ask.reason !== "string" || ask.reason.trim() === "" || ask.reason.length > 500) {
+        throw new RangeError("reason is 1 to 500 characters");
+    }
+    if (ask.farmId === undefined && ask.brokerId === undefined && ask.terminalIds === undefined) {
+        throw new RangeError("a bulk action names farmId, brokerId or terminalIds");
+    }
+    if (ask.terminalIds !== undefined && ask.terminalIds.length > 1000) {
+        throw new RangeError("terminalIds is at most 1000");
+    }
+    return {
+        reason: ask.reason,
+        confirm_open_positions: ask.confirmOpenPositions ?? false,
+        ...(ask.farmId === undefined ? {} : { farm_id: uuid("farmId", ask.farmId) }),
+        ...(ask.brokerId === undefined ? {} : { broker_id: uuid("brokerId", ask.brokerId) }),
+        ...(ask.terminalIds === undefined
+            ? {}
+            : { terminal_ids: ask.terminalIds.map((id) => uuid("terminalIds", id)) }),
+    };
+}
+/** How long to wait before the next read of a terminal still on its way. */
+function nextWaitMs(terminal, backoffMs, nowMs) {
+    const expected = terminal.state === "QUEUED" ? terminal.queue?.expected_start_at : undefined;
+    if (typeof expected === "string") {
+        const until = Date.parse(expected) - nowMs;
+        if (Number.isFinite(until))
+            return Math.min(Math.max(until, POLL_FROM_MS), QUEUED_CAP_MS);
+    }
+    return Math.min(backoffMs, POLL_CAP_MS);
+}
 /** Provision and inspect the terminals this key's tenant owns. */
 export class Terminals {
     #client;
@@ -129,4 +171,67 @@ export class Terminals {
             idempotencyKey: key,
         }));
     }
+    /**
+     * Read the terminal until it is no longer on its way to ACTIVE (REQUESTED, QUEUED, PROVISIONING,
+     * LOGGING_IN), or until `timeoutMs` has been waited. Returns the last read either way: ACTIVE,
+     * a state it settled in instead (FAILED, for one), or still on its way when the time ran out.
+     *
+     * A QUEUED terminal is read again at its `queue.expected_start_at` (between 2 s and a minute
+     * away), not on a fixed beat: its cell starts terminals a few at a time, so asking every two
+     * seconds tells nothing new. Any other state is read again after 2 s, doubling to 15 s.
+     */
+    async waitUntilActive(terminalId, options = {}) {
+        const timeoutMs = options.timeoutMs ?? 15 * 60_000;
+        if (typeof timeoutMs !== "number" || !(timeoutMs >= 0)) {
+            throw new RangeError("timeoutMs is 0 or more");
+        }
+        let waited = 0;
+        let backoff = POLL_FROM_MS;
+        let terminal = await this.get(terminalId);
+        while (ON_ITS_WAY.has(terminal.state) && waited < timeoutMs) {
+            const ms = Math.min(nextWaitMs(terminal, backoff, Date.now()), timeoutMs - waited);
+            await this.#client.pause(ms);
+            waited += ms;
+            backoff *= 2;
+            terminal = await this.get(terminalId);
+        }
+        return terminal;
+    }
+    /**
+     * Restart many of your terminals at once. Each is judged by the rules of a single restart; a
+     * refused one is listed in `refused` with its rule's code and the rest are taken. Each cell
+     * carries its share at its own pace, so the terminals already running on it are not slowed.
+     * Answered at once with the action and its expected finish; its items never expire.
+     */
+    async bulkRestart(ask) {
+        return this.#bulk("/terminals:restart", ask);
+    }
+    /** Retire many of your terminals at once, as {@link bulkRestart} restarts them. */
+    async bulkRetire(ask) {
+        return this.#bulk("/terminals:retire", ask);
+    }
+    /** A bulk action's progress: counts per state, what was refused, and its expected finish. */
+    async getBulkAction(bulkActionId) {
+        const id = uuid("bulkActionId", bulkActionId);
+        return (await this.#client.read({ method: "GET", path: `/bulk-actions/${id}` }));
+    }
+    /** Cancel a bulk action: its waiting items are cancelled, running ones finish. */
+    async cancelBulkAction(bulkActionId, options) {
+        const id = uuid("bulkActionId", bulkActionId);
+        return (await this.#client.write({
+            method: "POST",
+            path: `/bulk-actions/${id}/cancel`,
+            idempotencyKey: idempotencyKey(options.idempotencyKey),
+        }));
+    }
+    async #bulk(path, ask) {
+        const key = idempotencyKey(ask.idempotencyKey);
+        const body = bulkBody(ask);
+        return (await this.#client.write({
+            method: "POST",
+            path,
+            body,
+            idempotencyKey: key,
+        }));
+    }
 }

package/dist/trading-accounts.d.ts

@@ -0,0 +1,44 @@
+import type { MfxClient } from "./client.js";
+import type { components } from "./generated/api.js";
+import { type Page } from "./pages.js";
+/** One trading account at one venue, as the API describes it. */
+export type TradingAccount = components["schemas"]["TradingAccount"];
+/** The trading technology an account is on. */
+export type Venue = TradingAccount["venue"];
+/** An account's state, in words that hold on every venue. */
+export type AccountState = TradingAccount["state"];
+/** Live or demo. */
+export type AccountEnvironment = NonNullable<TradingAccount["environment"]>;
+/** Narrow the list on the platform, before the page is cut. */
+export interface TradingAccountFilter {
+    /** Only accounts on this venue, or on one of these. */
+    readonly venue?: Venue | readonly Venue[];
+    /** Only live, or only demo, accounts. */
+    readonly environment?: AccountEnvironment;
+    /** Only accounts in this state, or in one of these. */
+    readonly state?: AccountState | readonly AccountState[];
+}
+/** What {@link TradingAccounts.page} takes. */
+export interface TradingAccountPageOptions extends TradingAccountFilter {
+    /** The `nextCursor` of the page before; leave it out for the first page. */
+    readonly cursor?: string;
+    /** How many to a page, 1 to 200. */
+    readonly limit?: number;
+}
+/** Read the trading accounts this key's tenant holds. Needs `acct:read`. */
+export declare class TradingAccounts {
+    #private;
+    constructor(client: MfxClient);
+    /**
+     * One trading account, by its own id or by one of its terminals' ids. Another tenant's, or an id
+     * that is not an account of yours, is 404.
+     */
+    get(accountId: string): Promise<TradingAccount>;
+    /** One page of this tenant's trading accounts, newest first. One request. */
+    page(options?: TradingAccountPageOptions): Promise<Page<TradingAccount>>;
+    /**
+     * Every trading account, following the cursor, one request a page. There is no total. The
+     * filters narrow the list on the platform, so a filtered page is never short for being filtered.
+     */
+    list(options?: Omit<TradingAccountPageOptions, "cursor">): AsyncGenerator<TradingAccount, void, undefined>;
+}

package/dist/trading-accounts.js

@@ -0,0 +1,76 @@
+// `client.tradingAccounts`: the tenant's trading accounts over every venue.
+//
+// One trading account is one account at one venue: an MT5 account (run by one terminal, or two with
+// HA), and from the cTrader release a cTrader account. An MT5 account's id is its terminal's id, so
+// an id you already hold reads its account, and `get` also takes either HA terminal's id. Its state
+// is the venue-neutral word (CONNECTED, DEGRADED, REAUTH_NEEDED, ...); `client.terminals.get` has
+// the MT5 detail.
+//
+// DECISION: a namespace of its own beside `client.accounts`, which stays what it was: the balance,
+// positions and deals of a terminal's account. Folding the two together would give `accounts.get`
+// two meanings.
+import { limit as pageLimit, uuid } from "./arguments.js";
+import { everyItem, pageOf } from "./pages.js";
+function joined(name, value) {
+    if (value === undefined)
+        return undefined;
+    const words = typeof value === "string" ? [value] : value;
+    if (words.length === 0)
+        throw new RangeError(`${name} is one or more values; got none`);
+    for (const word of words) {
+        if (typeof word !== "string" || word === "")
+            throw new TypeError(`${name} is a list of words`);
+    }
+    return words.join(",");
+}
+/** Read the trading accounts this key's tenant holds. Needs `acct:read`. */
+export class TradingAccounts {
+    #client;
+    constructor(client) {
+        this.#client = client;
+    }
+    /**
+     * One trading account, by its own id or by one of its terminals' ids. Another tenant's, or an id
+     * that is not an account of yours, is 404.
+     */
+    async get(accountId) {
+        const id = uuid("accountId", accountId);
+        return (await this.#client.read({ method: "GET", path: `/accounts/${id}` }));
+    }
+    /** One page of this tenant's trading accounts, newest first. One request. */
+    async page(options = {}) {
+        const limit = pageLimit(options.limit);
+        if (options.cursor !== undefined && typeof options.cursor !== "string") {
+            throw new TypeError("cursor is the nextCursor of the page before");
+        }
+        if (options.environment !== undefined && typeof options.environment !== "string") {
+            throw new TypeError("environment is live or demo");
+        }
+        const body = await this.#client.read({
+            method: "GET",
+            path: "/accounts",
+            query: {
+                cursor: options.cursor,
+                limit,
+                venue: joined("venue", options.venue),
+                environment: options.environment,
+                state: joined("state", options.state),
+            },
+        });
+        return pageOf(body);
+    }
+    /**
+     * Every trading account, following the cursor, one request a page. There is no total. The
+     * filters narrow the list on the platform, so a filtered page is never short for being filtered.
+     */
+    list(options = {}) {
+        const limit = pageLimit(options.limit);
+        const rest = {
+            ...(limit === undefined ? {} : { limit }),
+            ...(options.venue === undefined ? {} : { venue: options.venue }),
+            ...(options.environment === undefined ? {} : { environment: options.environment }),
+            ...(options.state === undefined ? {} : { state: options.state }),
+        };
+        return everyItem((cursor) => this.page({ ...rest, ...(cursor === undefined ? {} : { cursor }) }));
+    }
+}

package/dist/version.d.ts

@@ -1,4 +1,4 @@
 /** This package's version. */
-export declare const VERSION = "0.2.2";
+export declare const VERSION = "0.3.0";
 /** What every request says it is, as a product token: the SDK's language and its version. */
-export declare const USER_AGENT = "mfx-sdk-typescript/0.2.2";
+export declare const USER_AGENT = "mfx-sdk-typescript/0.3.0";

package/dist/version.js

@@ -1,5 +1,5 @@
 // This package's version, in one place: exported by the package, and named by every request.
 /** This package's version. */
-export const VERSION = "0.2.2";
+export const VERSION = "0.3.0";
 /** What every request says it is, as a product token: the SDK's language and its version. */
 export const USER_AGENT = `mfx-sdk-typescript/${VERSION}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mfxhub/sdk",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Typed TypeScript client for the MFX Hub API: hosted trading terminals, market data, execution and a live event stream",
   "license": "Apache-2.0",
   "type": "module",