@mfxhub/sdk 0.1.2 → 0.2.1

package/dist/index.d.ts

@@ -11,16 +11,18 @@ export type { Answer, Budget, ClientOptions, RequestSpec } from "./client.js";
 export * from "./errors.js";
 export { Page } from "./pages.js";
 export { Catalog } from "./catalog.js";
-export type { Quote, QuoteOptions } from "./catalog.js";
-export { Execution } from "./execution.js";
+export type { BrokerCatalogue, CatalogSymbol, Quote, QuoteOptions, SymbolPage } from "./catalog.js";
+export type { MaintenanceWindowChanged, SymbolSpecChange, SymbolSpecChanged, TerminalConditionChanged, } from "./events.js";
+export { Accounts } from "./accounts.js";
+export type { Account, Deal, DealPageOptions, DealWindow, PendingOrder, PendingOrderList, Position, PositionList, } 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 type { Connector, StreamConnection, StreamEvent, StreamOptions, StreamStats, Timeframe, } from "./stream.js";
-export type { OrderType, PlaceOrder, Side } from "./execution.js";
+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, PageOptions, Redundancy, Terminal, TerminalState, } from "./terminals.js";
+export type { CreateTerminal, JournalLine, JournalOptions, PageOptions, Redundancy, Terminal, TerminalFilter, TerminalJournal, TerminalState, } from "./terminals.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";
-/** This package's version. */
-export declare const VERSION = "0.1.2";
+export { VERSION } from "./version.js";

package/dist/index.js

@@ -10,10 +10,10 @@ export { MfxClient, DEFAULT_READ_RETRIES, DEFAULT_TIMEOUT_MS } from "./client.js
 export * from "./errors.js";
 export { Page } from "./pages.js";
 export { Catalog } from "./catalog.js";
-export { Execution } from "./execution.js";
+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 { RequestSigner, SigningKey, signingMessage } from "./signing.js";
 export { KEY_HEADER, NONCE_HEADER, SIGNATURE_HEADER, TIMESTAMP_HEADER } from "./signing.js";
-/** This package's version. */
-export const VERSION = "0.1.2";
+export { VERSION } from "./version.js";

package/dist/stream.js

@@ -23,6 +23,7 @@
 // The upgrade is signed exactly as a REST request is, over `GET /v1/stream`.
 import WebSocket from "ws";
 import { AuthError, MfxError, MfxTransportError, errorFor } from "./errors.js";
+import { USER_AGENT } from "./version.js";
 /** The server says why it hung up. 4001 is the one reconnecting cannot fix. */
 export const CLOSE_REAUTHENTICATE = 4001;
 export const CLOSE_SLOW_CONSUMER = 4008;
@@ -225,7 +226,10 @@ export class MfxStream {
     /** Opens the connection. {@link MfxClient.stream} does this for you. */
     async open() {
         const path = new URL(this.#url).pathname;
-        this.#connection = await this.#connect(this.#url, this.#client.signer.headersFor("GET", path));
+        this.#connection = await this.#connect(this.#url, {
+            ...this.#client.signer.headersFor("GET", path),
+            "User-Agent": USER_AGENT,
+        });
         return this;
     }
     /** Subscribe to one channel. Subscribing twice is not an error. */

package/dist/terminals.d.ts

@@ -1,5 +1,5 @@
 import type { MfxClient } from "./client.js";
-import type { components } from "./generated/api.js";
+import type { components, operations } from "./generated/api.js";
 import { type Page } from "./pages.js";
 /** A terminal, as the API describes it. */
 export type Terminal = components["schemas"]["TenantTerminal"];
@@ -7,6 +7,24 @@ export type Terminal = components["schemas"]["TenantTerminal"];
 export type TerminalState = Terminal["state"];
 /** How a terminal is replicated. */
 export type Redundancy = components["schemas"]["TerminalCreate"]["redundancy"];
+/** The states the list can be narrowed to, as the contract declares them. */
+type ListState = NonNullable<NonNullable<operations["listTerminals"]["parameters"]["query"]>["state"]>;
+/** A terminal's journal: its lines newest first, and whether they were read live. */
+export type TerminalJournal = components["schemas"]["TerminalJournal"];
+/** One line of a terminal's MetaTrader journal. */
+export type JournalLine = components["schemas"]["JournalLine"];
+/** What {@link Terminals.journal} takes. */
+export interface JournalOptions {
+    /** How many lines, newest first: 1 to 200. The platform's default is 100. */
+    readonly lines?: number;
+}
+/** Narrow a terminal list in the query, before the page is cut. */
+export interface TerminalFilter {
+    /** Only terminals carrying every one of these labels, by exact key and value. At most 10. */
+    readonly labels?: Readonly<Record<string, string>>;
+    /** Only terminals in one of these states. */
+    readonly state?: ListState | ListState[number];
+}
 /** What {@link Terminals.create} takes. */
 export interface CreateTerminal {
     /** The broker, from the catalogue. */
@@ -25,7 +43,7 @@ export interface CreateTerminal {
     readonly redundancy?: Redundancy;
 }
 /** What {@link Terminals.page} takes. */
-export interface PageOptions {
+export interface PageOptions extends TerminalFilter {
     /** The `nextCursor` of the page before; leave it out for the first page. */
     readonly cursor?: string;
     /** How many to a page, 1 to 200. */
@@ -45,11 +63,21 @@ export declare class Terminals {
     get(terminalId: string): Promise<Terminal>;
     /** One page of this tenant's terminals, newest first. One request. */
     page(options?: PageOptions): Promise<Page<Terminal>>;
-    /** Every terminal, following the cursor, one request a page. There is no total. */
-    list(options?: Pick<PageOptions, "limit">): AsyncGenerator<Terminal, void, undefined>;
+    /**
+     * Every terminal, following the cursor, one request a page. There is no total. `labels` and
+     * `state` narrow the list on the platform, so a filtered page is never short for being filtered.
+     */
+    list(options?: Omit<PageOptions, "cursor">): AsyncGenerator<Terminal, void, undefined>;
+    /**
+     * The terminal's MetaTrader journal, newest first. While it runs the lines are read from its
+     * cell (`from: "live"`); after it stops they are the last lines its cell kept, for 24 hours
+     * (`from: "last_words"`). Account numbers are masked. A terminal with no lines held is 409.
+     */
+    journal(terminalId: string, options?: JournalOptions): Promise<TerminalJournal>;
     /**
      * Ask for a terminal. Answered at once in state REQUESTED; the move to a cell happens after.
      * Sent once and never retried: if the answer is lost, send the same idempotency key again.
      */
     create(request: CreateTerminal): Promise<Terminal>;
 }
+export {};

package/dist/terminals.js

@@ -10,6 +10,32 @@
 // exception, because it is the SDK's own type, not the API's.
 import { idempotencyKey, limit as pageLimit, uuid } from "./arguments.js";
 import { everyItem, pageOf } from "./pages.js";
+function labelQuery(labels) {
+    if (labels === undefined)
+        return undefined;
+    const pairs = Object.entries(labels);
+    if (pairs.length > 10)
+        throw new RangeError("labels is at most 10 pairs");
+    return pairs.map(([key, value]) => {
+        if (key === "" || key.includes(":")) {
+            throw new RangeError(`a label key is not empty and has no colon: ${JSON.stringify(key)}`);
+        }
+        if (typeof value !== "string")
+            throw new TypeError(`label ${key} is a string`);
+        if (key.length + 1 + value.length > 200) {
+            throw new RangeError(`label ${key} is over 200 characters`);
+        }
+        return `${key}:${value}`;
+    });
+}
+function stateQuery(state) {
+    if (state === undefined)
+        return undefined;
+    const states = typeof state === "string" ? [state] : state;
+    if (states.length === 0)
+        throw new RangeError("state is one or more states; got none");
+    return states.join(",");
+}
 /**
  * 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
@@ -38,16 +64,46 @@ export class Terminals {
         const body = await this.#client.read({
             method: "GET",
             path: "/terminals",
-            query: { cursor: options.cursor, limit },
+            query: {
+                cursor: options.cursor,
+                limit,
+                label: labelQuery(options.labels),
+                state: stateQuery(options.state),
+            },
         });
         return pageOf(body);
     }
-    /** Every terminal, following the cursor, one request a page. There is no total. */
+    /**
+     * Every terminal, following the cursor, one request a page. There is no total. `labels` and
+     * `state` narrow the list on the platform, so a filtered page is never short for being filtered.
+     */
     list(options = {}) {
         const limit = pageLimit(options.limit);
-        return everyItem((cursor) => this.page({
-            ...(cursor === undefined ? {} : { cursor }),
+        const rest = {
             ...(limit === undefined ? {} : { limit }),
+            ...(options.labels === undefined ? {} : { labels: options.labels }),
+            ...(options.state === undefined ? {} : { state: options.state }),
+        };
+        return everyItem((cursor) => this.page({ ...rest, ...(cursor === undefined ? {} : { cursor }) }));
+    }
+    /**
+     * The terminal's MetaTrader journal, newest first. While it runs the lines are read from its
+     * cell (`from: "live"`); after it stops they are the last lines its cell kept, for 24 hours
+     * (`from: "last_words"`). Account numbers are masked. A terminal with no lines held is 409.
+     */
+    async journal(terminalId, options = {}) {
+        const id = uuid("terminalId", terminalId);
+        const lines = options.lines;
+        if (lines !== undefined && (typeof lines !== "number" || !Number.isInteger(lines))) {
+            throw new TypeError("lines is a whole number");
+        }
+        if (lines !== undefined && (lines < 1 || lines > 200)) {
+            throw new RangeError(`lines is 1 to 200; got ${lines}`);
+        }
+        return (await this.#client.read({
+            method: "GET",
+            path: `/terminals/${id}/journal`,
+            query: { lines },
         }));
     }
     /**

package/dist/version.d.ts

@@ -0,0 +1,4 @@
+/** This package's version. */
+export declare const VERSION = "0.2.1";
+/** 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.1";

package/dist/version.js

@@ -0,0 +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.1";
+/** 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.1.2",
+  "version": "0.2.1",
   "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",