@mfxhub/sdk 0.0.0 → 0.1.1

package/dist/stream.js

@@ -0,0 +1,387 @@
+// `client.stream()`: the multiplexed WebSocket.
+//
+// One connection carries every channel a tenant is watching: ticks, closed candles, platform
+// events and execution results. The caller writes one loop:
+//
+//     const stream = await client.stream();
+//     await stream.subscribe(Channel.md(serverId, "EURUSD.sd"));
+//     await stream.subscribe(Channel.results(terminalId));
+//     for await (const event of stream) { ... }
+//
+// What this module is opinionated about, each because the alternative loses data quietly:
+// - Channels are keyed by id, never by display name. `Channel` builds the keys and refuses one
+//   the platform would.
+// - A reconnect resumes what can be resumed and says so about the rest. Events, results, account
+//   and expert channels carry a per-channel `seq` and are resumed from the last one seen. Ticks and
+//   candles are not replayed, by design (a stale tick is worse than none), so they subscribe again.
+// - Almost nothing is buffered on the caller's behalf. When the caller falls behind, the socket is
+//   paused, so a slow consumer meets real backpressure and is eventually dropped by the server
+//   with 4008, which this reports, instead of reading minutes-old prices believing they are live.
+// - Gaps are counted, not hidden. `seq` increases per channel; anything missing is arithmetic, and
+//   `stats.dropped` carries the total.
+//
+// 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";
+/** 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;
+export const CLOSE_LIFETIME = 4009;
+/** Exactly the platform's own pattern for a channel key (`StreamChannel`). */
+const CHANNEL = /^(md:[0-9a-f-]{36}:[^:]+|candles:[0-9a-f-]{36}:[^:]+:(M1|M5|M15|M30|H1|H4|D1|W1|MN1)|events|results:[0-9a-f-]{36}|account:[0-9a-f-]{36}|ea:[0-9a-f-]{36}|book:[0-9a-f-]{36}:[^:]+)$/;
+/**
+ * These resume from the last seq after a reconnect. `account:` answers a resume with a fresh
+ * snapshot rather than a replay, which is still what it needs. `book:` is a state the platform
+ * sends whole on every subscribe, so subscribing again loses nothing.
+ */
+const REPLAYABLE = ["events", "results:", "account:", "ea:"];
+function checked(channel) {
+    if (!CHANNEL.test(channel)) {
+        throw new RangeError(`${JSON.stringify(channel)} is not a channel key the platform accepts. Ids are uuids and ` +
+            "a symbol carries no colon; see StreamChannel in the API description.");
+    }
+    return channel;
+}
+const replayable = (channel) => REPLAYABLE.some((p) => channel.startsWith(p));
+/** Builds the channel keys the platform accepts, from ids rather than names. */
+export const Channel = {
+    /** Every platform event for this tenant. */
+    events: "events",
+    /** Ticks for one symbol on one server, in the broker's own name for it. */
+    md: (serverId, symbol) => checked(`md:${serverId}:${symbol}`),
+    /** Closed candles. Only closed ones are published; a forming candle is not a fact yet. */
+    candles: (serverId, symbol, timeframe) => checked(`candles:${serverId}:${symbol}:${timeframe}`),
+    /** Execution results for one terminal: where a command id is finally answered. */
+    results: (terminalId) => checked(`results:${terminalId}`),
+    /** One terminal's live account: a snapshot, then marks. */
+    account: (terminalId) => checked(`account:${terminalId}`),
+    /** What the tenant's own expert advisor on this terminal writes. Needs `ea:read`. */
+    ea: (terminalId) => checked(`ea:${terminalId}`),
+    /** The symbol's order book, whole, each time it changes. */
+    book: (serverId, symbol) => checked(`book:${serverId}:${symbol}`),
+};
+/** The connection ended. `code` is the WebSocket close code, `reason` the server's words. */
+export class StreamClosed extends MfxError {
+    code;
+    reason;
+    name = "StreamClosed";
+    constructor(code, reason = "") {
+        super(reason === "" ? `stream closed ${code}` : `stream closed ${code}: ${reason}`);
+        this.code = code;
+        this.reason = reason;
+    }
+}
+/** One message on one channel. */
+export class StreamMessage {
+    channel;
+    seq;
+    type;
+    data;
+    base;
+    constructor(channel, 
+    /** Increases per channel; a jump is counted in `stats.dropped`. */
+    seq, 
+    /** The event type on `events` and `results` (`command.completed`); null on a tick or candle. */
+    type, data, 
+    /** `account:` only: the seq of the snapshot this message applies to. */
+    base = null) {
+        this.channel = channel;
+        this.seq = seq;
+        this.type = type;
+        this.data = data;
+        this.base = base;
+    }
+}
+/** The position asked for is older than the replay window: read the current state over REST. */
+export class Resync {
+    channel;
+    constructor(channel) {
+        this.channel = channel;
+    }
+}
+/**
+ * The platform refused one channel; every other channel carries on. The subscription is dropped,
+ * so a reconnect does not ask for it again and collect the same refusal for ever.
+ */
+export class ChannelRefused {
+    channel;
+    code;
+    message;
+    details;
+    constructor(channel, 
+    /** The platform's own code: `not_found`, `forbidden`, `not_subscribed`. */
+    code, message, details = {}) {
+        this.channel = channel;
+        this.code = code;
+        this.message = message;
+        this.details = details;
+    }
+}
+/** How many frames may wait for the caller before the socket is paused. */
+const HIGH_WATER = 64;
+/** The default transport, over `ws`, with backpressure: the socket pauses while frames wait. */
+export const wsConnector = (url, headers) => new Promise((resolve, reject) => {
+    const socket = new WebSocket(url, { headers: { ...headers } });
+    const frames = [];
+    const waiting = [];
+    let ended = null;
+    socket.on("message", (data) => {
+        // binaryType is ws's default, "nodebuffer": every frame arrives as one Buffer.
+        const text = data.toString("utf8");
+        const next = waiting.shift();
+        if (next !== undefined) {
+            next.resolve(text);
+            return;
+        }
+        frames.push(text);
+        if (frames.length >= HIGH_WATER)
+            socket.pause();
+    });
+    socket.on("close", (code, reason) => {
+        ended = new StreamClosed(code, reason.toString("utf8"));
+        for (const next of waiting.splice(0))
+            next.reject(ended);
+    });
+    // Once the connection is open this reject does nothing: a later error is followed by "close".
+    socket.on("error", (error) => {
+        reject(new MfxTransportError(`the stream could not be opened: ${error.message}`, false));
+    });
+    socket.once("open", () => {
+        resolve({
+            send: (text) => new Promise((done, fail) => {
+                // ws calls back with null, not undefined, once the frame is written.
+                socket.send(text, (error) => {
+                    if (error instanceof Error)
+                        fail(ended ?? new StreamClosed(1006, error.message));
+                    else
+                        done();
+                });
+            }),
+            recv: () => {
+                const frame = frames.shift();
+                if (frame !== undefined) {
+                    if (frames.length < HIGH_WATER / 2)
+                        socket.resume();
+                    return Promise.resolve(frame);
+                }
+                if (ended !== null)
+                    return Promise.reject(ended);
+                return new Promise((done, fail) => waiting.push({ resolve: done, reject: fail }));
+            },
+            close: () => new Promise((done) => {
+                if (socket.readyState === WebSocket.CLOSED) {
+                    done();
+                    return;
+                }
+                socket.once("close", () => {
+                    done();
+                });
+                socket.close(1000);
+            }),
+        });
+    });
+});
+/** The stream's address beside the REST base: `api.dev.mfxhub.com/v1` is `ws.dev.mfxhub.com/v1/stream`. */
+export function streamUrl(baseUrl) {
+    const url = baseUrl
+        .replace(/\/+$/, "")
+        .replace(/^https:\/\//, "wss://")
+        .replace(/^http:\/\//, "ws://")
+        .replace("://api.", "://ws.");
+    return url.endsWith("/stream") ? url : `${url}/stream`;
+}
+/** The multiplexed stream. Opened by `await client.stream()`; closed by `close()`. */
+export class MfxStream {
+    #client;
+    #connect;
+    #url;
+    #maxReconnects;
+    /** Each subscribed channel, in the order asked for, with the last seq seen on it. */
+    #channels = new Map();
+    #stats = {
+        reconnects: 0,
+        dropped: 0,
+        resyncs: 0,
+        slowConsumerDrops: 0,
+        lifetimeReconnects: 0,
+        refused: 0,
+    };
+    #connection = null;
+    /** Use {@link MfxClient.stream}. */
+    constructor(client, options = {}) {
+        this.#client = client;
+        this.#connect = options.connect ?? wsConnector;
+        this.#url = options.url ?? streamUrl(client.baseUrl);
+        this.#maxReconnects = options.maxReconnects ?? null;
+    }
+    /** What has been missed so far. A snapshot; it never changes under the caller. */
+    get stats() {
+        return { ...this.#stats };
+    }
+    /** The channels currently subscribed, in the order they were asked for. */
+    get channels() {
+        return [...this.#channels.keys()];
+    }
+    /** 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));
+        return this;
+    }
+    /** Subscribe to one channel. Subscribing twice is not an error. */
+    async subscribe(channel) {
+        checked(channel);
+        if (!this.#channels.has(channel))
+            this.#channels.set(channel, null);
+        await this.#send({ op: "subscribe", ch: channel });
+    }
+    /**
+     * Bring one channel back up to date from the last seq seen, when the caller has noticed from
+     * the data itself that it is behind. On a channel that does not replay, or one with no seq yet,
+     * this subscribes instead: there is no position to resume from.
+     */
+    async resume(channel) {
+        checked(channel);
+        const last = this.#channels.get(channel);
+        if (last === undefined || last === null || !replayable(channel)) {
+            await this.subscribe(channel);
+            return;
+        }
+        await this.#send({ op: "resume", ch: channel, after_seq: last });
+    }
+    /** Stop watching a channel, and stop subscribing to it again after a reconnect. */
+    async unsubscribe(channel) {
+        this.#channels.delete(channel);
+        await this.#send({ op: "unsubscribe", ch: channel });
+    }
+    /** Close the connection, if one is open. */
+    async close() {
+        const connection = this.#connection;
+        this.#connection = null;
+        if (connection !== null)
+            await connection.close();
+    }
+    async *[Symbol.asyncIterator]() {
+        for (;;) {
+            const event = await this.next();
+            if (event === null)
+                return;
+            yield event;
+        }
+    }
+    /**
+     * The next event, reconnecting underneath as needed; null once the stream is over. Throws an
+     * AuthError on 4001, and the platform's typed error for an error that names no channel.
+     */
+    async next() {
+        for (;;) {
+            const connection = this.#connection;
+            if (connection === null)
+                return null;
+            let raw;
+            try {
+                raw = await connection.recv();
+            }
+            catch (error) {
+                if (!(error instanceof StreamClosed))
+                    throw error;
+                if (!(await this.#reopen(error)))
+                    return null;
+                continue;
+            }
+            const event = this.#interpret(raw);
+            if (event !== null)
+                return event;
+        }
+    }
+    #interpret(raw) {
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return null; // not a frame of this protocol; nothing a caller can act on
+        }
+        const message = (typeof parsed === "object" && parsed !== null ? parsed : {});
+        const channel = typeof message.ch === "string" ? message.ch : "";
+        if (message.op === "error") {
+            const body = (typeof message.error === "object" && message.error !== null ? message.error : {});
+            const code = typeof body.code === "string" ? body.code : "stream_error";
+            const text = typeof body.message === "string"
+                ? body.message
+                : `stream error on ${channel === "" ? "the connection" : channel}`;
+            const details = (typeof body.details === "object" && body.details !== null ? body.details : {});
+            if (channel !== "") {
+                this.#channels.delete(channel);
+                this.#bump("refused");
+                return new ChannelRefused(channel, code, text, details);
+            }
+            // About the connection itself: typed by the platform's code, with no HTTP status.
+            throw errorFor(code, text, 0, details);
+        }
+        if (message.op === "resync") {
+            this.#bump("resyncs");
+            // The replay window has passed: forget the position so the next reconnect does not ask
+            // for the same dead seq, and so the jump to the new seq is not counted as a gap.
+            if (this.#channels.has(channel))
+                this.#channels.set(channel, null);
+            return new Resync(channel);
+        }
+        if (message.op !== "msg")
+            return null; // an ack, or an op added after this SDK shipped
+        const seq = Number.isInteger(message.seq) ? message.seq : null;
+        const last = this.#channels.get(channel);
+        if (last !== undefined && seq !== null) {
+            if (last !== null && seq > last + 1)
+                this.#bump("dropped", seq - last - 1);
+            this.#channels.set(channel, seq);
+        }
+        const data = message.data;
+        return new StreamMessage(channel, seq, typeof message.type === "string" ? message.type : null, typeof data === "object" && data !== null ? data : {}, Number.isInteger(message.base) ? message.base : null);
+    }
+    /** Come back after a close, or say the stream is over. 4001 throws: reconnecting cannot help. */
+    async #reopen(closed) {
+        if (closed.code === CLOSE_REAUTHENTICATE) {
+            this.#connection = null;
+            throw new AuthError(closed.reason === ""
+                ? "the stream's credentials were rotated, expired or revoked"
+                : closed.reason, 401, "auth_error");
+        }
+        if (closed.code === CLOSE_SLOW_CONSUMER)
+            this.#bump("slowConsumerDrops");
+        if (closed.code === CLOSE_LIFETIME)
+            this.#bump("lifetimeReconnects");
+        if (this.#maxReconnects !== null && this.#stats.reconnects >= this.#maxReconnects) {
+            this.#connection = null;
+            return false;
+        }
+        this.#bump("reconnects");
+        // The client's own backoff, so the stream and the reads lean on this tenant's quota alike.
+        await this.#client.pause(this.#client.backoffMs(this.#stats.reconnects));
+        await this.open();
+        for (const [channel, last] of [...this.#channels]) {
+            if (replayable(channel) && last !== null) {
+                await this.#send({ op: "resume", ch: channel, after_seq: last });
+            }
+            else {
+                // Ticks and candles are never replayed, so their position means nothing across a
+                // reconnect; forgetting it stops the next seq being counted as a gap.
+                this.#channels.set(channel, null);
+                await this.#send({ op: "subscribe", ch: channel });
+            }
+        }
+        return true;
+    }
+    async #send(message) {
+        const connection = this.#connection;
+        if (connection === null)
+            throw new StreamClosed(1006, "the stream is not open");
+        await connection.send(JSON.stringify(message));
+    }
+    #bump(counter, by = 1) {
+        this.#stats = { ...this.#stats, [counter]: this.#stats[counter] + by };
+    }
+    toString() {
+        return `MfxStream(${this.#url}, channels=${this.#channels.size})`;
+    }
+}

package/dist/terminals.d.ts

@@ -0,0 +1,55 @@
+import type { MfxClient } from "./client.js";
+import type { components } from "./generated/api.js";
+import { type Page } from "./pages.js";
+/** A terminal, as the API describes it. */
+export type Terminal = components["schemas"]["TenantTerminal"];
+/** The states a terminal moves through. Only ACTIVE can be used; see {@link isUsable}. */
+export type TerminalState = Terminal["state"];
+/** How a terminal is replicated. */
+export type Redundancy = components["schemas"]["TerminalCreate"]["redundancy"];
+/** What {@link Terminals.create} takes. */
+export interface CreateTerminal {
+    /** The broker, from the catalogue. */
+    readonly brokerId: string;
+    /** The broker's server the terminal logs in to. */
+    readonly serverId: string;
+    /** Required: the same key sent again returns the same terminal, not a second one. */
+    readonly idempotencyKey: string;
+    /** Leave it out and the platform chooses a farm; the one it chose is on the answer. */
+    readonly farmId?: string;
+    readonly streaming?: boolean;
+    readonly execution?: boolean;
+    /** The broker's own symbol names (`EURUSD.sd`). */
+    readonly instruments?: readonly string[];
+    readonly labels?: Readonly<Record<string, string>>;
+    readonly redundancy?: Redundancy;
+}
+/** What {@link Terminals.page} takes. */
+export interface PageOptions {
+    /** 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;
+}
+/**
+ * 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.
+ */
+export declare function isUsable(terminal: Pick<Terminal, "state">): boolean;
+/** Provision and inspect the terminals this key's tenant owns. */
+export declare class Terminals {
+    #private;
+    constructor(client: MfxClient);
+    /** One terminal: its state, since when, and its observed conditions. Another tenant's is 404. */
+    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>;
+    /**
+     * 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>;
+}

package/dist/terminals.js

@@ -0,0 +1,76 @@
+// `client.terminals`: a tenant's terminals.
+//
+// The slice a tenant's first hour is made of: ask for a terminal, watch it reach ACTIVE, read it.
+// Every write takes an idempotency key, and it has no default.
+//
+// DECISION: options are camelCase, as TypeScript callers write them, and what comes back is the
+// API's own object, typed from the contract, with its field names as the API sends them
+// (`state_since`, `created_at`). Renaming every field would put a hand-written copy of the
+// contract between the caller and the API, and it would drift. The Page wrapper is the one
+// 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";
+/**
+ * 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.
+ */
+export function isUsable(terminal) {
+    return terminal.state === "ACTIVE";
+}
+/** Provision and inspect the terminals this key's tenant owns. */
+export class Terminals {
+    #client;
+    constructor(client) {
+        this.#client = client;
+    }
+    /** One terminal: its state, since when, and its observed conditions. Another tenant's is 404. */
+    async get(terminalId) {
+        const id = uuid("terminalId", terminalId);
+        return (await this.#client.read({ method: "GET", path: `/terminals/${id}` }));
+    }
+    /** One page of this tenant's terminals, 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");
+        }
+        const body = await this.#client.read({
+            method: "GET",
+            path: "/terminals",
+            query: { cursor: options.cursor, limit },
+        });
+        return pageOf(body);
+    }
+    /** Every terminal, following the cursor, one request a page. There is no total. */
+    list(options = {}) {
+        const limit = pageLimit(options.limit);
+        return everyItem((cursor) => this.page({
+            ...(cursor === undefined ? {} : { cursor }),
+            ...(limit === undefined ? {} : { limit }),
+        }));
+    }
+    /**
+     * 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.
+     */
+    async create(request) {
+        const key = idempotencyKey(request.idempotencyKey);
+        const body = {
+            broker_id: uuid("brokerId", request.brokerId),
+            server_id: uuid("serverId", request.serverId),
+            streaming: request.streaming ?? false,
+            execution: request.execution ?? false,
+            redundancy: request.redundancy ?? "none",
+            ...(request.farmId === undefined ? {} : { farm_id: uuid("farmId", request.farmId) }),
+            ...(request.instruments === undefined ? {} : { instruments: [...request.instruments] }),
+            ...(request.labels === undefined ? {} : { labels: { ...request.labels } }),
+        };
+        return (await this.#client.write({
+            method: "POST",
+            path: "/terminals",
+            body,
+            idempotencyKey: key,
+        }));
+    }
+}

package/package.json

@@ -1,9 +1,66 @@
 {
   "name": "@mfxhub/sdk",
-  "version": "0.0.0",
-  "description": "Placeholder that reserves the name for the MFX Hub TypeScript SDK. Do not install; the first real release is 0.1.0.",
+  "version": "0.1.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",
-  "homepage": "https://mfxhub.com",
-  "repository": { "type": "git", "url": "git+https://github.com/mfx-platform/mfx-sdk-typescript.git" },
-  "files": ["README.md"]
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "mfx",
+    "mfx-hub",
+    "trading",
+    "market-data",
+    "trading-api"
+  ],
+  "homepage": "https://docs.mfxhub.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mfx-platform/mfx-sdk-typescript.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mfx-platform/mfx-sdk-typescript/issues"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --check .",
+    "test": "vitest run --coverage",
+    "test:conformance": "vitest run --config vitest.conformance.config.ts",
+    "gen": "openapi-typescript spec/openapi.yaml -o src/generated/api.ts && prettier --write src/generated/api.ts",
+    "check:gen": "node tools/check-generated.mjs"
+  },
+  "dependencies": {
+    "ws": "^8.22.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^22.20.5",
+    "@types/ws": "^8.18.2",
+    "@vitest/coverage-v8": "^5.0.5",
+    "eslint": "^10.13.0",
+    "openapi-typescript": "^7.13.0",
+    "prettier": "^3.9.10",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.72.1",
+    "vitest": "^5.0.5"
+  }
 }