@mfxhub/sdk 0.0.0 → 0.1.0

package/dist/client.js

@@ -0,0 +1,200 @@
+/**
+ * `MfxClient`: one signed connection to the MFX Hub API.
+ *
+ * Every request is signed with the tenant's Ed25519 key. Reads that are rate limited are retried
+ * after the platform's own `Retry-After`; writes are never retried, because a retried write is a
+ * second order. Failures become typed errors from `errors.ts`.
+ */
+import { MfxApiError, MfxTimeout, MfxTransportError, errorFor, retryAfterSeconds, } from "./errors.js";
+import { RequestSigner } from "./signing.js";
+import { Catalog } from "./catalog.js";
+import { Execution } from "./execution.js";
+import { MfxStream } from "./stream.js";
+import { Terminals } from "./terminals.js";
+/** Default time a single request may take. */
+export const DEFAULT_TIMEOUT_MS = 30_000;
+/** How many times a rate-limited read is tried again. */
+export const DEFAULT_READ_RETRIES = 3;
+/** The longest the client waits between attempts when the platform names no delay. */
+const BACKOFF_CAP_MS = 30_000;
+/** Connection-phase failures: the request was never sent. */
+const NOT_SENT = new Set([
+    "ECONNREFUSED",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "ENETUNREACH",
+    "EHOSTUNREACH",
+    "UND_ERR_CONNECT_TIMEOUT",
+]);
+const wait = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+});
+/** A tenant's connection to MFX Hub. */
+export class MfxClient {
+    #signer;
+    #base;
+    #timeoutMs;
+    #readRetries;
+    #sleep;
+    #fetch;
+    #random;
+    #budget = null;
+    /** The terminals this key's tenant owns. */
+    terminals;
+    /** Order entry. Every call resolves to a result; none rejects. */
+    execution;
+    /** Brokers, symbols and quotes. */
+    catalog;
+    /**
+     * @param baseUrl the API's base, including the version: `https://api.mfxhub.com/v1`, or
+     *   `https://api.dev.mfxhub.com/v1` for development
+     * @param keyId the API key's id
+     * @param privateKey its private key: PEM, the base64 of its 32 bytes, or a SigningKey
+     */
+    constructor(baseUrl, keyId, privateKey, options = {}) {
+        this.#base = new URL(baseUrl.replace(/\/+$/, "") + "/");
+        this.#signer = new RequestSigner(keyId, privateKey, options.clock);
+        this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.#readRetries = options.readRetries ?? DEFAULT_READ_RETRIES;
+        this.#sleep = options.sleep ?? wait;
+        this.#fetch = options.fetch ?? fetch;
+        this.#random = options.random ?? Math.random;
+        this.terminals = new Terminals(this);
+        this.execution = new Execution(this);
+        this.catalog = new Catalog(this);
+    }
+    /** The id of the key this client signs with. Safe to log, unlike the private key. */
+    get keyId() {
+        return this.#signer.keyId;
+    }
+    /** The REST base this client was pointed at. The stream's address is derived from it. */
+    get baseUrl() {
+        return this.#base.href.replace(/\/$/, "");
+    }
+    /** What the key had left when MFX Hub last answered; null before the first answer. */
+    get budget() {
+        return this.#budget;
+    }
+    /** The signer, for the stream's upgrade. Not part of the public surface. */
+    get signer() {
+        return this.#signer;
+    }
+    /**
+     * Jittered exponential backoff for an attempt, when the platform gave no delay: up to 1 s, 2 s,
+     * 4 s ... capped at 30 s. The reads and the stream's reconnects share it, so they lean on this
+     * tenant's quota at the same rate.
+     */
+    backoffMs(attempt) {
+        return Math.round(this.#random() * Math.min(1000 * 2 ** attempt, BACKOFF_CAP_MS));
+    }
+    /**
+     * The multiplexed event stream, opened: subscribe, then iterate. Close it when done.
+     * Reconnects underneath, resuming what replays; see {@link MfxStream}.
+     */
+    stream(options = {}) {
+        return new MfxStream(this, options).open();
+    }
+    /** How the client waits; the stream uses it between reconnects. */
+    pause(ms) {
+        return this.#sleep(ms);
+    }
+    /** A read: retried after a 429 with the platform's own delay; a failure throws its typed error. */
+    async read(spec) {
+        for (let attempt = 0;; attempt++) {
+            const answer = await this.send(spec);
+            if (answer.status === 429 && attempt < this.#readRetries) {
+                const told = retryAfterSeconds(answer.headers.get("Retry-After"));
+                await this.#sleep(told === null ? this.backoffMs(attempt) : 1000 * told);
+                continue;
+            }
+            throwFor(answer, spec);
+            return answer.body;
+        }
+    }
+    /** A write: sent once, never retried; a failure throws its typed error. */
+    async write(spec) {
+        const answer = await this.send(spec);
+        throwFor(answer, spec);
+        return answer.body;
+    }
+    /** One attempt, signed afresh. Transport faults become MfxTransportError or MfxTimeout. */
+    async send(spec) {
+        const url = new URL(spec.path.replace(/^\//, ""), this.#base);
+        for (const [name, value] of Object.entries(spec.query ?? {})) {
+            if (value !== null && value !== undefined)
+                url.searchParams.set(name, String(value));
+        }
+        const body = spec.body === undefined ? new Uint8Array() : Buffer.from(JSON.stringify(spec.body));
+        const headers = {
+            Accept: "application/json",
+            ...this.#signer.headersFor(spec.method, url.pathname + url.search, body),
+        };
+        if (spec.body !== undefined)
+            headers["Content-Type"] = "application/json";
+        if (spec.idempotencyKey !== undefined)
+            headers["Idempotency-Key"] = spec.idempotencyKey;
+        let response;
+        try {
+            response = await this.#fetch(url, {
+                method: spec.method,
+                headers,
+                ...(spec.body === undefined ? {} : { body }),
+                signal: AbortSignal.timeout(this.#timeoutMs),
+            });
+        }
+        catch (error) {
+            throw transportError(error, spec);
+        }
+        const text = await response.text();
+        this.#noteBudget(response.headers);
+        let parsed = null;
+        if (text !== "") {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = text;
+            }
+        }
+        return { status: response.status, headers: response.headers, body: parsed };
+    }
+    #noteBudget(headers) {
+        const remaining = headers.get("X-MFX-Budget-Remaining");
+        if (remaining !== null && Number.isFinite(Number(remaining))) {
+            this.#budget = {
+                remaining: Number(remaining),
+                source: headers.get("X-MFX-Budget-Source") ?? "",
+            };
+        }
+    }
+    toString() {
+        return `MfxClient(${this.baseUrl}, ${this.keyId})`;
+    }
+}
+/** The typed error a failed answer means, or nothing for a success. */
+export function throwFor(answer, spec) {
+    if (answer.status < 400)
+        return;
+    const body = answer.body;
+    const error = typeof body === "object" && body !== null
+        ? body.error
+        : undefined;
+    const code = typeof error?.code === "string" ? error.code : "";
+    const message = typeof error?.message === "string" ? error.message : `${spec.method} ${spec.path} failed`;
+    const details = typeof error?.details === "object" && error.details !== null
+        ? error.details
+        : {};
+    throw errorFor(code, message, answer.status, details, retryAfterSeconds(answer.headers.get("Retry-After")));
+}
+function transportError(error, spec) {
+    const what = `${spec.method} ${spec.path}`;
+    if (error instanceof DOMException &&
+        (error.name === "TimeoutError" || error.name === "AbortError")) {
+        return new MfxTimeout(`${what}: no answer in time`);
+    }
+    const cause = error?.cause;
+    const code = typeof cause?.code === "string" ? cause.code : "";
+    const text = error instanceof Error ? error.message : String(error);
+    return new MfxTransportError(`${what}: ${text}${code ? ` (${code})` : ""}`, !NOT_SENT.has(code));
+}
+export { MfxApiError };

package/dist/decimals.d.ts

@@ -0,0 +1,10 @@
+/**
+ * One non-negative decimal as the contract writes it: plain digits, no sign, no exponent, no
+ * leading zeros (`1E+3` is `"1000"`, `1.5e-3` is `"0.0015"`). Digits are never rounded or dropped.
+ *
+ * @param name the argument's name, for the message
+ * @param value a decimal string, such as `"0.01"`
+ */
+export declare function decimal(name: string, value: unknown): string;
+/** A decimal the API sent, kept as its string; anything else reads as absent. */
+export declare function decimalOut(value: unknown): string | null;

package/dist/decimals.js

@@ -0,0 +1,51 @@
+// Prices, volumes and money are decimal strings, in and out.
+//
+// A JavaScript `number` is a binary float: 0.07 * 3 is 0.21000000000000002, and position sizing is
+// arithmetic, so a computed volume is the ordinary case. Taking a number would put that error on
+// the wire. So a number is refused before anything is sent, with a message that says what to pass.
+const DECIMAL = /^\+?(\d*)(?:\.(\d*))?(?:[eE]([+-]?\d+))?$/;
+/** No price or volume needs more; a larger exponent would only build a huge string. */
+const MAX_EXPONENT = 100;
+/**
+ * One non-negative decimal as the contract writes it: plain digits, no sign, no exponent, no
+ * leading zeros (`1E+3` is `"1000"`, `1.5e-3` is `"0.0015"`). Digits are never rounded or dropped.
+ *
+ * @param name the argument's name, for the message
+ * @param value a decimal string, such as `"0.01"`
+ */
+export function decimal(name, value) {
+    if (typeof value === "number") {
+        throw new TypeError(`${name} is a decimal string, not a number: a computed number carries binary error ` +
+            `(0.07 * 3 is 0.21000000000000002), and MFX Hub takes decimals as strings so nothing is ` +
+            `lost. Pass "${String(value)}" only if that is exactly the value you mean.`);
+    }
+    if (typeof value !== "string") {
+        throw new TypeError(`${name} is a decimal string; got ${typeof value}`);
+    }
+    const match = DECIMAL.exec(value.trim());
+    const whole = match?.[1] ?? "";
+    const fraction = match?.[2] ?? "";
+    if (match === null || whole + fraction === "") {
+        throw new RangeError(`${name} is not a non-negative decimal: ${JSON.stringify(value)}`);
+    }
+    const exponent = Number(match[3] ?? "0");
+    if (Math.abs(exponent) > MAX_EXPONENT) {
+        throw new RangeError(`${name} has an exponent beyond ±${MAX_EXPONENT}: ${value}`);
+    }
+    const digits = whole + fraction;
+    // Where the decimal point falls in `digits` once the exponent is applied.
+    const point = whole.length + exponent;
+    const padded = point <= 0
+        ? "0".repeat(1 - point) + digits
+        : point > digits.length
+            ? digits + "0".repeat(point - digits.length)
+            : digits;
+    const at = point <= 0 ? 1 : point;
+    const intPart = padded.slice(0, at).replace(/^0+(?=\d)/, "");
+    const fracPart = padded.slice(at);
+    return fracPart === "" ? intPart : `${intPart}.${fracPart}`;
+}
+/** A decimal the API sent, kept as its string; anything else reads as absent. */
+export function decimalOut(value) {
+    return typeof value === "string" && value !== "" ? value : null;
+}

package/dist/errors.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Every failure a read can raise, typed by the platform's `error.code`.
+ *
+ * The code decides; the HTTP status only when the code is one this version does not know, so a
+ * code the platform adds later still arrives as a typed error rather than failing the caller.
+ * Execution methods never raise: they return an `ExecutionResult` instead.
+ */
+/** Every failure this SDK raises. */
+export declare class MfxError extends Error {
+    name: string;
+}
+/**
+ * The request never got an answer: DNS, TCP, TLS, a dropped connection.
+ *
+ * `mayHaveReached` is false only when the connection never opened, so nothing was sent. A
+ * connection that dropped after the request was written may have delivered it.
+ */
+export declare class MfxTransportError extends MfxError {
+    readonly mayHaveReached: boolean;
+    name: string;
+    constructor(message: string, mayHaveReached?: boolean);
+}
+/** No answer in time. Never retried: the request may have arrived. */
+export declare class MfxTimeout extends MfxTransportError {
+    name: string;
+}
+/** The platform answered with an error. */
+export declare class MfxApiError extends MfxError {
+    /** The HTTP status; 0 for an error sent on the stream. */
+    readonly status: number;
+    /** The platform's error code, as it arrived. */
+    readonly code: string;
+    /** What the platform said about it, such as the field that was wrong. */
+    readonly details: Readonly<Record<string, unknown>>;
+    /** How long the platform asked the caller to wait, from Retry-After. */
+    readonly retryAfterS: number | null;
+    name: string;
+    constructor(message: string, 
+    /** The HTTP status; 0 for an error sent on the stream. */
+    status: number, 
+    /** The platform's error code, as it arrived. */
+    code: string, 
+    /** What the platform said about it, such as the field that was wrong. */
+    details?: Readonly<Record<string, unknown>>, 
+    /** How long the platform asked the caller to wait, from Retry-After. */
+    retryAfterS?: number | null);
+}
+/** The request cannot be taken as it was sent; `details` says which part. */
+export declare class ValidationError extends MfxApiError {
+    name: string;
+}
+/** The request is not signed by a key the platform knows. */
+export declare class AuthError extends MfxApiError {
+    name: string;
+}
+/** The key may not do this. */
+export declare class ForbiddenError extends MfxApiError {
+    name: string;
+}
+/** The operator has disabled the tenant. */
+export declare class TenantDisabledError extends ForbiddenError {
+    name: string;
+}
+/** The operator has suspended the tenant. */
+export declare class TenantSuspendedError extends ForbiddenError {
+    name: string;
+}
+/** A planned maintenance window; `details.ends_at` says when it ends. */
+export declare class MaintenanceError extends ForbiddenError {
+    name: string;
+}
+/** No such thing; also the answer for another tenant's id. */
+export declare class NotFoundError extends MfxApiError {
+    name: string;
+}
+/** The request conflicts with what already exists. */
+export declare class ConflictError extends MfxApiError {
+    name: string;
+}
+/** The thing exists and is not in a state this can be done in. */
+export declare class StateError extends ConflictError {
+    name: string;
+}
+/** The terminal cannot be placed. */
+export declare class PlacementError extends ConflictError {
+    name: string;
+}
+/** MFX Hub does not support this broker or server now; the message says why. */
+export declare class UnsupportedBrokerError extends ConflictError {
+    name: string;
+}
+/** Too many requests; `retryAfterS` says how long to wait. */
+export declare class RateLimitError extends MfxApiError {
+    name: string;
+}
+/** The tenant's terminal or broker did not answer. */
+export declare class UpstreamError extends MfxApiError {
+    name: string;
+}
+/** A store of the platform's own did not answer; `retryAfterS` says when to try again. */
+export declare class DependencyUnavailableError extends UpstreamError {
+    name: string;
+}
+/** An answer from the network's edge, not from MFX Hub (a 502 or 504). */
+export declare class EdgeError extends UpstreamError {
+    name: string;
+}
+/** MFX Hub failed, and it is not the caller's request that is wrong. */
+export declare class InternalError extends MfxApiError {
+    name: string;
+}
+/** The typed error for a failure the platform described, on a call's answer or the stream. */
+export declare function errorFor(code: string, message: string, status: number, details?: Readonly<Record<string, unknown>>, retryAfterS?: number | null): MfxApiError;
+/** Seconds from a Retry-After header, or null when there is none or it cannot be read. */
+export declare function retryAfterSeconds(header: string | null): number | null;

package/dist/errors.js

@@ -0,0 +1,162 @@
+/**
+ * Every failure a read can raise, typed by the platform's `error.code`.
+ *
+ * The code decides; the HTTP status only when the code is one this version does not know, so a
+ * code the platform adds later still arrives as a typed error rather than failing the caller.
+ * Execution methods never raise: they return an `ExecutionResult` instead.
+ */
+/** Every failure this SDK raises. */
+export class MfxError extends Error {
+    name = "MfxError";
+}
+/**
+ * The request never got an answer: DNS, TCP, TLS, a dropped connection.
+ *
+ * `mayHaveReached` is false only when the connection never opened, so nothing was sent. A
+ * connection that dropped after the request was written may have delivered it.
+ */
+export class MfxTransportError extends MfxError {
+    mayHaveReached;
+    name = "MfxTransportError";
+    constructor(message, mayHaveReached = true) {
+        super(message);
+        this.mayHaveReached = mayHaveReached;
+    }
+}
+/** No answer in time. Never retried: the request may have arrived. */
+export class MfxTimeout extends MfxTransportError {
+    name = "MfxTimeout";
+}
+/** The platform answered with an error. */
+export class MfxApiError extends MfxError {
+    status;
+    code;
+    details;
+    retryAfterS;
+    name = "MfxApiError";
+    constructor(message, 
+    /** The HTTP status; 0 for an error sent on the stream. */
+    status, 
+    /** The platform's error code, as it arrived. */
+    code, 
+    /** What the platform said about it, such as the field that was wrong. */
+    details = {}, 
+    /** How long the platform asked the caller to wait, from Retry-After. */
+    retryAfterS = null) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.details = details;
+        this.retryAfterS = retryAfterS;
+    }
+}
+/** The request cannot be taken as it was sent; `details` says which part. */
+export class ValidationError extends MfxApiError {
+    name = "ValidationError";
+}
+/** The request is not signed by a key the platform knows. */
+export class AuthError extends MfxApiError {
+    name = "AuthError";
+}
+/** The key may not do this. */
+export class ForbiddenError extends MfxApiError {
+    name = "ForbiddenError";
+}
+/** The operator has disabled the tenant. */
+export class TenantDisabledError extends ForbiddenError {
+    name = "TenantDisabledError";
+}
+/** The operator has suspended the tenant. */
+export class TenantSuspendedError extends ForbiddenError {
+    name = "TenantSuspendedError";
+}
+/** A planned maintenance window; `details.ends_at` says when it ends. */
+export class MaintenanceError extends ForbiddenError {
+    name = "MaintenanceError";
+}
+/** No such thing; also the answer for another tenant's id. */
+export class NotFoundError extends MfxApiError {
+    name = "NotFoundError";
+}
+/** The request conflicts with what already exists. */
+export class ConflictError extends MfxApiError {
+    name = "ConflictError";
+}
+/** The thing exists and is not in a state this can be done in. */
+export class StateError extends ConflictError {
+    name = "StateError";
+}
+/** The terminal cannot be placed. */
+export class PlacementError extends ConflictError {
+    name = "PlacementError";
+}
+/** MFX Hub does not support this broker or server now; the message says why. */
+export class UnsupportedBrokerError extends ConflictError {
+    name = "UnsupportedBrokerError";
+}
+/** Too many requests; `retryAfterS` says how long to wait. */
+export class RateLimitError extends MfxApiError {
+    name = "RateLimitError";
+}
+/** The tenant's terminal or broker did not answer. */
+export class UpstreamError extends MfxApiError {
+    name = "UpstreamError";
+}
+/** A store of the platform's own did not answer; `retryAfterS` says when to try again. */
+export class DependencyUnavailableError extends UpstreamError {
+    name = "DependencyUnavailableError";
+}
+/** An answer from the network's edge, not from MFX Hub (a 502 or 504). */
+export class EdgeError extends UpstreamError {
+    name = "EdgeError";
+}
+/** MFX Hub failed, and it is not the caller's request that is wrong. */
+export class InternalError extends MfxApiError {
+    name = "InternalError";
+}
+const BY_CODE = {
+    validation_error: ValidationError,
+    auth_error: AuthError,
+    forbidden: ForbiddenError,
+    tenant_disabled: TenantDisabledError,
+    tenant_suspended: TenantSuspendedError,
+    maintenance: MaintenanceError,
+    not_found: NotFoundError,
+    conflict: ConflictError,
+    state_error: StateError,
+    placement_error: PlacementError,
+    broker_not_supported: UnsupportedBrokerError,
+    rate_limited: RateLimitError,
+    upstream_error: UpstreamError,
+    dependency_unavailable: DependencyUnavailableError,
+    internal_error: InternalError,
+};
+const BY_STATUS = {
+    400: ValidationError,
+    401: AuthError,
+    403: ForbiddenError,
+    404: NotFoundError,
+    409: ConflictError,
+    413: ValidationError,
+    422: ValidationError,
+    429: RateLimitError,
+    500: InternalError,
+    502: EdgeError,
+    503: UpstreamError,
+    504: EdgeError,
+};
+/** The typed error for a failure the platform described, on a call's answer or the stream. */
+export function errorFor(code, message, status, details = {}, retryAfterS = null) {
+    const Kind = BY_CODE[code] ?? BY_STATUS[status] ?? MfxApiError;
+    return new Kind(message, status, code, details, retryAfterS);
+}
+/** Seconds from a Retry-After header, or null when there is none or it cannot be read. */
+export function retryAfterSeconds(header) {
+    if (header === null || header.trim() === "")
+        return null;
+    const seconds = Number(header);
+    if (Number.isFinite(seconds))
+        return Math.max(0, seconds);
+    const at = Date.parse(header);
+    return Number.isNaN(at) ? null : Math.max(0, (at - Date.now()) / 1000);
+}

package/dist/execution.d.ts

@@ -0,0 +1,48 @@
+import { type MfxClient } from "./client.js";
+import type { components } from "./generated/api.js";
+import { type ExecutionResult } from "./results.js";
+type OrderPlace = components["schemas"]["OrderPlace"];
+export type Side = OrderPlace["side"];
+export type OrderType = OrderPlace["order_type"];
+/** What {@link Execution.placeOrder} takes. */
+export interface PlaceOrder {
+    /** The broker's own symbol name (`EURUSD.sd`); MFX never renames an instrument. */
+    readonly symbol: string;
+    readonly side: Side;
+    /** In lots, as a decimal string: `"0.01"`. A number is refused. */
+    readonly volume: string;
+    /** Required: the same key sent again returns the original command, not a second order. */
+    readonly idempotencyKey: string;
+    /** `market` unless given. */
+    readonly orderType?: OrderType;
+    /** A pending order's price; for `stop_limit`, the stop price where the order wakes up. */
+    readonly price?: string;
+    /** For `stop_limit` only: the limit order placed when the stop price is reached. */
+    readonly stopLimitPrice?: string;
+    readonly sl?: string;
+    readonly tp?: string;
+    /** How far from the requested price a market order may fill, in points. */
+    readonly deviationPoints?: number;
+    /** When a pending order expires. */
+    readonly expiresAt?: Date | string;
+    /** How long the platform may hold the command before it gives up, 1,000 to 60,000 ms. */
+    readonly expiresInMs?: number;
+    /** The expert advisor number the order is tagged with. */
+    readonly magic?: number;
+    /** Up to 31 characters; longer is refused, because MT5 would cut it without saying so. */
+    readonly comment?: string;
+}
+/** Order entry for one tenant. Every method resolves to a result; none rejects. */
+export declare class Execution {
+    #private;
+    constructor(client: MfxClient);
+    /**
+     * 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.
+     *
+     * Throws only for a wrong argument, before anything is sent: a number where a decimal string
+     * belongs, a missing idempotency key, a comment over 31 characters.
+     */
+    placeOrder(terminalId: string, order: PlaceOrder): Promise<ExecutionResult>;
+}
+export {};