@mfxhub/sdk 0.0.0 → 0.1.1

package/dist/execution.js

@@ -0,0 +1,119 @@
+// `client.execution`: placing orders.
+//
+// Every method here resolves to an ExecutionResult and never rejects for anything the platform or
+// the network does. A transport fault, a timeout, a rate limit, a refusal and a broker rejection
+// are all outcomes of trying to trade. Only a wrong argument throws, before anything is sent.
+//
+// Three rules show up in every signature:
+// - The idempotency key is required and has no default. A retry reuses the same key and gets the
+//   original command back with `duplicate: true`, never a second order.
+// - Nothing is retried automatically: not a timeout (the order may have been placed), not a rate
+//   limit, not a 5xx. The SDK reports; the caller decides, from `retryable`.
+// - Prices and volumes are decimal strings; a number is refused (see decimals.ts).
+import { idempotencyKey, uuid } from "./arguments.js";
+import { throwFor } from "./client.js";
+import { decimal } from "./decimals.js";
+import { MaintenanceError, MfxApiError, MfxTimeout, MfxTransportError, RateLimitError, } from "./errors.js";
+import { concluded, fromCommand } from "./results.js";
+function whole(name, value, min, max) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "number" || !Number.isInteger(value)) {
+        throw new TypeError(`${name} is a whole number`);
+    }
+    if (value < min || value > max)
+        throw new RangeError(`${name} is ${min} to ${max}; got ${value}`);
+    return value;
+}
+function orderBody(order) {
+    const side = order.side;
+    if (side !== "buy" && side !== "sell")
+        throw new TypeError(`side is "buy" or "sell"`);
+    if (typeof order.symbol !== "string" || order.symbol === "") {
+        throw new TypeError("symbol is the broker's symbol name");
+    }
+    if (order.comment !== undefined && order.comment.length > 31) {
+        throw new RangeError("comment is at most 31 characters; MT5 would cut a longer one");
+    }
+    const expiresAt = order.expiresAt instanceof Date ? order.expiresAt.toISOString() : order.expiresAt;
+    const optional = {
+        order_type: order.orderType,
+        price: order.price === undefined ? undefined : decimal("price", order.price),
+        stop_limit_price: order.stopLimitPrice === undefined
+            ? undefined
+            : decimal("stopLimitPrice", order.stopLimitPrice),
+        sl: order.sl === undefined ? undefined : decimal("sl", order.sl),
+        tp: order.tp === undefined ? undefined : decimal("tp", order.tp),
+        deviation_points: whole("deviationPoints", order.deviationPoints, 0, 2 ** 31 - 1),
+        expires_at: expiresAt,
+        expires_in_ms: whole("expiresInMs", order.expiresInMs, 1000, 60_000),
+        magic: whole("magic", order.magic, 0, Number.MAX_SAFE_INTEGER),
+        comment: order.comment,
+    };
+    return {
+        symbol: order.symbol,
+        side,
+        volume: decimal("volume", order.volume),
+        ...Object.fromEntries(Object.entries(optional).filter(([, v]) => v !== undefined)),
+    };
+}
+/** Order entry for one tenant. Every method resolves to a result; none rejects. */
+export class Execution {
+    #client;
+    constructor(client) {
+        this.#client = client;
+    }
+    /**
+     * 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.
+     */
+    async placeOrder(terminalId, order) {
+        const id = uuid("terminalId", terminalId);
+        const key = idempotencyKey(order.idempotencyKey);
+        const body = orderBody(order);
+        return this.#command({ method: "POST", path: `/terminals/${id}/orders`, body, idempotencyKey: key }, key);
+    }
+    /** Sends one execution call, once, and turns everything it can do into a result. */
+    async #command(spec, key) {
+        const started = performance.now();
+        const elapsed = () => performance.now() - started;
+        const what = `${spec.method} ${spec.path}`;
+        let answer;
+        try {
+            answer = await this.#client.send(spec);
+        }
+        catch (error) {
+            if (error instanceof MfxTimeout) {
+                // Never retried, by the SDK or by anyone: the order may have reached the broker.
+                return concluded("timeout", key, elapsed(), `${what}: ${error.message}`);
+            }
+            // A connection that never opened cannot have placed anything; one that dropped after the
+            // order was sent may have, and then the result reads UNKNOWN.
+            const reached = !(error instanceof MfxTransportError) || error.mayHaveReached;
+            return concluded("transport_error", key, elapsed(), `${what}: ${String(error)}`, {
+                mayHaveReached: reached,
+            });
+        }
+        try {
+            throwFor(answer, spec);
+        }
+        catch (error) {
+            if (error instanceof MaintenanceError) {
+                const ends = error.details.ends_at;
+                const retryAt = typeof ends === "string" ? new Date(ends) : null;
+                return concluded("maintenance", key, elapsed(), error.message, {
+                    retryAt: retryAt !== null && Number.isNaN(retryAt.getTime()) ? null : retryAt,
+                });
+            }
+            if (error instanceof RateLimitError) {
+                return concluded("rate_limited", key, elapsed(), error.message);
+            }
+            // throwFor throws only the API's typed errors: every other answer is a refusal.
+            return concluded("refused", key, elapsed(), `${what}: ${error.message}`);
+        }
+        return fromCommand(answer.body, key, elapsed());
+    }
+}