@mfxhub/sdk 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -4,7 +4,38 @@ Every release of `@mfxhub/sdk`, newest first. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
 [Semantic Versioning](https://semver.org/).
 
-## Unreleased
+## 0.2.0
+
+### Added
+
+- `terminals.journal(terminalId, { lines })`: the terminal's MetaTrader journal, newest first, 1 to
+  200 lines. While the terminal runs the lines are read from it (`from: "live"`); after it stops
+  they are the last lines it kept, for 24 hours (`from: "last_words"`). A terminal with no lines
+  held throws `StateError`; a cell that does not answer throws `UpstreamError`.
+- `terminals.page` and `terminals.list` take `labels` (every pair must match) and `state` (one or
+  several), applied by the platform before the page is cut.
+- `catalog.catalogues(brokerId)`: one row per server and account type you hold a catalogue for,
+  with its `catalogue_hash`, to re-read a symbol list only when it changed.
+- The API description is re-vendored. New on what comes back: `broker_words` and `refusal_kind` on
+  a terminal's conditions and on `terminal.condition_changed`, `server_kind` on a terminal, path,
+  ISIN, exchange, category, base currency, basis and calculation mode on a catalogue symbol,
+  `source` (`live` or `last_known`) on a page of symbols, and the values `added`, `came_back`,
+  `description` and `identity` for the `change` of `symbol.spec_changed`.
+- A new event, `maintenance.window_changed`, arrives on the `events` channel like any other. The
+  payload types `MaintenanceWindowChanged`, `TerminalConditionChanged`, `SymbolSpecChanged` and
+  `SymbolSpecChange` are exported.
+- The rest of order entry on `client.execution`: `modifyOrder`, `cancelOrder`, `modifyPosition`,
+  `closePosition`, `closePositionPartial`, `closePositionBy`, `setTrailingStop` and
+  `clearTrailingStop`. Like `placeOrder`, each takes a required idempotency key, sends only what
+  you give, takes decimals as strings, and resolves to an `ExecutionResult` without ever
+  rejecting. A wrong argument (a ticket that is not a positive whole number, a modify that
+  changes nothing, a comment over 31 characters) throws before anything is sent.
+- `execution.waitFor(commandId, { timeoutMs })` reads a command until it is final, pausing 200 ms
+  and doubling up to 2 s, and returns the last answer when the time runs out. A result that is
+  not final is never a reason to send again.
+- `client.accounts`: `account`, `positions` and `pendingOrders` from the terminal's latest
+  snapshot, and closed deals inside a required window, a page at a time (`dealsPage`) or every
+  page (`deals`).
 
 ## 0.1.2
 

package/README.md

@@ -105,3 +105,11 @@ must fail until it is removed. To move to a new suite release:
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) to propose a change, and [SECURITY.md](SECURITY.md) to report a
 security problem.
+
+## Licence and trademarks
+
+Licensed under the [Apache License 2.0](LICENSE).
+
+MFX Hub is an independent service and is not affiliated with, endorsed by or sponsored by
+MetaQuotes Ltd. MetaTrader is a registered trademark of MetaQuotes Ltd., used here only to say which
+trading platform MFX Hub's terminals are compatible with.

package/dist/accounts.d.ts

@@ -0,0 +1,47 @@
+import type { MfxClient } from "./client.js";
+import type { components } from "./generated/api.js";
+import { type Page } from "./pages.js";
+/** The account's figures: balance, equity, margin, as of its latest snapshot. */
+export type Account = components["schemas"]["Account"];
+/** Every open position, as one snapshot with its `as_of`. */
+export type PositionList = components["schemas"]["PositionList"];
+/** One open position. */
+export type Position = components["schemas"]["Position"];
+/** Every pending order, as one snapshot with its `as_of`. */
+export type PendingOrderList = components["schemas"]["PendingOrderList"];
+/** One pending order. */
+export type PendingOrder = components["schemas"]["PendingOrder"];
+/** One closed deal. */
+export type Deal = components["schemas"]["Deal"];
+/** The window {@link Accounts.deals} reads. Both ends are required. */
+export interface DealWindow {
+    readonly from: Date;
+    readonly to: Date;
+    /** Only the deals of this position. */
+    readonly position?: number;
+    /** How many to a page, 1 to 200. */
+    readonly limit?: number;
+}
+/** What {@link Accounts.dealsPage} takes. */
+export interface DealPageOptions extends DealWindow {
+    /** The `nextCursor` of the page before; leave it out for the first page. */
+    readonly cursor?: string;
+}
+/** Read the trading account behind a terminal: figures, positions, pending orders and deals. */
+export declare class Accounts {
+    #private;
+    constructor(client: MfxClient);
+    /** The account's figures. Another tenant's terminal is not found. */
+    account(terminalId: string): Promise<Account>;
+    /** Every open position, as one snapshot with its `as_of`. */
+    positions(terminalId: string): Promise<PositionList>;
+    /** Every pending order, as one snapshot with its `as_of`. */
+    pendingOrders(terminalId: string): Promise<PendingOrderList>;
+    /**
+     * One page of closed deals inside a window, newest first. The window is required, by the API
+     * and so by this: an unbounded history read is the query that takes a database down.
+     */
+    dealsPage(terminalId: string, options: DealPageOptions): Promise<Page<Deal>>;
+    /** Every closed deal inside the window, following the cursor, one request a page. */
+    deals(terminalId: string, window: DealWindow): AsyncGenerator<Deal, void, undefined>;
+}

package/dist/accounts.js

@@ -0,0 +1,79 @@
+// `client.accounts`: what a terminal's trading account holds.
+//
+// The account, its open positions and its pending orders are read from the terminal's latest
+// snapshot, each with its `as_of`: a change made a moment ago can take a few seconds to show, so
+// read again rather than treat its absence as a failure. Closed deals are history: read inside a
+// window, a page at a time.
+//
+// As elsewhere in the SDK, what comes back is the API's own object, typed from the contract, with
+// its field names as the API sends them.
+import { limit as pageLimit, uuid } from "./arguments.js";
+import { everyItem, pageOf } from "./pages.js";
+function instant(name, value) {
+    if (!(value instanceof Date) || Number.isNaN(value.getTime())) {
+        throw new TypeError(`${name} is a Date; a deals window has both ends`);
+    }
+    return value.toISOString();
+}
+/** Read the trading account behind a terminal: figures, positions, pending orders and deals. */
+export class Accounts {
+    #client;
+    constructor(client) {
+        this.#client = client;
+    }
+    /** The account's figures. Another tenant's terminal is not found. */
+    async account(terminalId) {
+        const id = uuid("terminalId", terminalId);
+        return (await this.#client.read({
+            method: "GET",
+            path: `/terminals/${id}/account`,
+        }));
+    }
+    /** Every open position, as one snapshot with its `as_of`. */
+    async positions(terminalId) {
+        const id = uuid("terminalId", terminalId);
+        const path = `/terminals/${id}/positions`;
+        return (await this.#client.read({ method: "GET", path }));
+    }
+    /** Every pending order, as one snapshot with its `as_of`. */
+    async pendingOrders(terminalId) {
+        const id = uuid("terminalId", terminalId);
+        const path = `/terminals/${id}/orders/pending`;
+        return (await this.#client.read({ method: "GET", path }));
+    }
+    /**
+     * One page of closed deals inside a window, newest first. The window is required, by the API
+     * and so by this: an unbounded history read is the query that takes a database down.
+     */
+    async dealsPage(terminalId, options) {
+        const id = uuid("terminalId", terminalId);
+        const from = instant("from", options.from);
+        const to = instant("to", options.to);
+        if (options.to.getTime() < options.from.getTime()) {
+            throw new RangeError("the deals window ends before it starts");
+        }
+        if (options.cursor !== undefined && typeof options.cursor !== "string") {
+            throw new TypeError("cursor is the nextCursor of the page before");
+        }
+        if (options.position !== undefined &&
+            (!Number.isSafeInteger(options.position) || options.position < 1)) {
+            throw new TypeError("position is a positive whole number, the position's ticket");
+        }
+        const body = await this.#client.read({
+            method: "GET",
+            path: `/terminals/${id}/history/deals`,
+            query: {
+                from,
+                to,
+                position: options.position,
+                cursor: options.cursor,
+                limit: pageLimit(options.limit),
+            },
+        });
+        return pageOf(body);
+    }
+    /** Every closed deal inside the window, following the cursor, one request a page. */
+    deals(terminalId, window) {
+        return everyItem((cursor) => this.dealsPage(terminalId, { ...window, ...(cursor === undefined ? {} : { cursor }) }));
+    }
+}

package/dist/catalog.d.ts

@@ -2,6 +2,12 @@ import type { MfxClient } from "./client.js";
 import type { components } from "./generated/api.js";
 /** One symbol's current quote, with its age and whether the market can be traded. */
 export type Quote = components["schemas"]["SymbolQuote"];
+/** One server and account type a tenant holds a catalogue for, with a hash of the whole list. */
+export type BrokerCatalogue = components["schemas"]["BrokerCatalogue"];
+/** A catalogue symbol, with its path, ISIN, exchange, category and calculation fields. */
+export type CatalogSymbol = components["schemas"]["Symbol"];
+/** A page of catalogue symbols; `source` says whether they are live or the last known. */
+export type SymbolPage = components["schemas"]["SymbolPage"];
 /** Which of a tenant's servers and account types a symbol is meant on. */
 export interface QuoteOptions {
     /** Needed when the symbol is on more than one of your servers (409 `ambiguous_symbol`). */
@@ -22,4 +28,11 @@ export declare class Catalog {
      * @param symbol the broker's own symbol name (`EURUSD.sd`)
      */
     quote(brokerId: string, symbol: string, options?: QuoteOptions): Promise<Quote>;
+    /**
+     * One row per server and account type the tenant holds a catalogue for on this broker, each
+     * with `catalogue_hash`. The hash changes when a symbol is added, removed, comes back, or its
+     * specification, description or identity changes, and never on a quote: compare it to the last
+     * one you saw to re-read only what changed. A broker with no catalogue of yours gives `[]`.
+     */
+    catalogues(brokerId: string): Promise<readonly BrokerCatalogue[]>;
 }

package/dist/catalog.js

@@ -36,4 +36,18 @@ export class Catalog {
         });
         return body;
     }
+    /**
+     * One row per server and account type the tenant holds a catalogue for on this broker, each
+     * with `catalogue_hash`. The hash changes when a symbol is added, removed, comes back, or its
+     * specification, description or identity changes, and never on a quote: compare it to the last
+     * one you saw to re-read only what changed. A broker with no catalogue of yours gives `[]`.
+     */
+    async catalogues(brokerId) {
+        const broker = uuid("brokerId", brokerId);
+        const body = (await this.#client.read({
+            method: "GET",
+            path: `/brokers/${broker}/catalogues`,
+        }));
+        return body.items;
+    }
 }

package/dist/client.d.ts

@@ -7,6 +7,7 @@
  */
 import { MfxApiError } from "./errors.js";
 import { RequestSigner, type SigningKey } from "./signing.js";
+import { Accounts } from "./accounts.js";
 import { Catalog } from "./catalog.js";
 import { Execution } from "./execution.js";
 import { MfxStream, type StreamOptions } from "./stream.js";
@@ -40,7 +41,8 @@ export interface RequestSpec {
     readonly method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
     /** The path after the version, such as `/terminals/{id}`, with ids already filled in. */
     readonly path: string;
-    readonly query?: Readonly<Record<string, string | number | boolean | null | undefined>>;
+    /** A list value is sent as a repeated parameter (`label=a:b&label=c:d`). */
+    readonly query?: Readonly<Record<string, string | number | boolean | readonly string[] | null | undefined>>;
     readonly body?: unknown;
     /** Required on every write; sent as the Idempotency-Key header. */
     readonly idempotencyKey?: string;
@@ -60,6 +62,8 @@ export declare class MfxClient {
     readonly execution: Execution;
     /** Brokers, symbols and quotes. */
     readonly catalog: Catalog;
+    /** The trading account behind a terminal: figures, positions, pending orders and deals. */
+    readonly accounts: Accounts;
     /**
      * @param baseUrl the API's base, including the version: `https://api.mfxhub.com/v1`, or
      *   `https://api.dev.mfxhub.com/v1` for development

package/dist/client.js

@@ -7,6 +7,7 @@
  */
 import { MfxApiError, MfxTimeout, MfxTransportError, errorFor, retryAfterSeconds, } from "./errors.js";
 import { RequestSigner } from "./signing.js";
+import { Accounts } from "./accounts.js";
 import { Catalog } from "./catalog.js";
 import { Execution } from "./execution.js";
 import { MfxStream } from "./stream.js";
@@ -45,6 +46,8 @@ export class MfxClient {
     execution;
     /** Brokers, symbols and quotes. */
     catalog;
+    /** The trading account behind a terminal: figures, positions, pending orders and deals. */
+    accounts;
     /**
      * @param baseUrl the API's base, including the version: `https://api.mfxhub.com/v1`, or
      *   `https://api.dev.mfxhub.com/v1` for development
@@ -62,6 +65,7 @@ export class MfxClient {
         this.terminals = new Terminals(this);
         this.execution = new Execution(this);
         this.catalog = new Catalog(this);
+        this.accounts = new Accounts(this);
     }
     /** The id of the key this client signs with. Safe to log, unlike the private key. */
     get keyId() {
@@ -121,8 +125,15 @@ export class MfxClient {
     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)
+            if (value === null || value === undefined)
+                continue;
+            if (typeof value === "object") {
+                for (const each of value)
+                    url.searchParams.append(name, each);
+            }
+            else {
                 url.searchParams.set(name, String(value));
+            }
         }
         const body = spec.body === undefined ? new Uint8Array() : Buffer.from(JSON.stringify(spec.body));
         const headers = {

package/dist/events.d.ts

@@ -0,0 +1,13 @@
+import type { components } from "./generated/api.js";
+/** `terminal.condition_changed`: a condition's status moved; carries `broker_words` and `refusal_kind`. */
+export type TerminalConditionChanged = components["schemas"]["TerminalConditionChanged"];
+/** `maintenance.window_changed`: a window was announced, started, moved, ended or cancelled. */
+export type MaintenanceWindowChanged = components["schemas"]["MaintenanceWindowChanged"];
+/** `symbol.spec_changed`: a symbol on a catalogue of yours changed. */
+export type SymbolSpecChanged = components["schemas"]["SymbolSpecChanged"];
+/**
+ * What changed on a symbol: `spec`, `trading`, `sessions`, `removed`, `added`, `came_back`,
+ * `description` or `identity`. `before` is null for `added` and `after` is null for `removed`; for
+ * `came_back` and `description` both are specs. The platform does not send `identity` yet.
+ */
+export type SymbolSpecChange = SymbolSpecChanged["change"];

package/dist/events.js

@@ -0,0 +1,5 @@
+// The `data` of the platform events a tenant receives on the `events` channel and as webhooks,
+// typed from the contract. The stream delivers every event type the platform sends, including
+// ones this version has not heard of, with `type` as the platform wrote it; these types describe
+// the payloads that are known. On the stream every value is text, as on every event.
+export {};

package/dist/execution.d.ts

@@ -32,6 +32,58 @@ export interface PlaceOrder {
     /** Up to 31 characters; longer is refused, because MT5 would cut it without saying so. */
     readonly comment?: string;
 }
+/** Every command on an existing order or position takes its key; nothing else is required. */
+export interface Keyed {
+    /** Required: the same key sent again returns the original command, not a second one. */
+    readonly idempotencyKey: string;
+}
+/** What {@link Execution.modifyOrder} takes: only what changes; at least one field. */
+export interface ModifyOrder extends Keyed {
+    readonly price?: string;
+    readonly stopLimitPrice?: string;
+    readonly sl?: string;
+    readonly tp?: string;
+    /** A new expiry; `null` removes it and the order stays until cancelled. */
+    readonly expiresAt?: Date | string | null;
+}
+/** What {@link Execution.modifyPosition} takes: a stop loss, a take profit, or both. */
+export interface ModifyPosition extends Keyed {
+    readonly sl?: string;
+    readonly tp?: string;
+}
+/** What {@link Execution.closePosition} takes. */
+export interface ClosePosition extends Keyed {
+    /** How far from the price the close may fill, in points; the platform's default is 20. */
+    readonly deviationPoints?: number;
+    /** The closing deal's comment, up to 31 characters; absent, it takes the position's own. */
+    readonly comment?: string;
+}
+/** What {@link Execution.closePositionPartial} takes. */
+export interface ClosePositionPartial extends ClosePosition {
+    /** The volume to close, in lots, as a decimal string, inside the symbol's step. */
+    readonly volume: string;
+}
+/** What {@link Execution.closePositionBy} takes. */
+export interface ClosePositionBy extends Keyed {
+    /** The opposite position, in the same symbol, that this one is closed against. */
+    readonly byTicket: number;
+}
+/** What {@link Execution.setTrailingStop} takes. */
+export interface SetTrailingStop extends Keyed {
+    /** How far behind the best price the stop loss follows, as a price distance: `"0.0020"`. */
+    readonly distance: string;
+}
+/** What {@link Execution.waitFor} takes. */
+export interface WaitFor {
+    /** How long to keep reading, 1 ms to 10 minutes; 30 s unless given. */
+    readonly timeoutMs?: number;
+    /** Carried into the result only, so a retry can reuse it. */
+    readonly idempotencyKey?: string;
+}
+/** The first pause between reads of a command, doubled each time up to {@link POLL_CAP_MS}. */
+export declare const POLL_FROM_MS = 200;
+/** The longest pause between two reads of a command. */
+export declare const POLL_CAP_MS = 2000;
 /** Order entry for one tenant. Every method resolves to a result; none rejects. */
 export declare class Execution {
     #private;
@@ -44,6 +96,38 @@ export declare class Execution {
      * belongs, a missing idempotency key, a comment over 31 characters.
      */
     placeOrder(terminalId: string, order: PlaceOrder): Promise<ExecutionResult>;
+    /**
+     * Amend a pending order's price, stops or expiry; at least one must change. Its volume, side,
+     * type and symbol cannot be amended: cancel it and place another.
+     */
+    modifyOrder(terminalId: string, ticket: number, change: ModifyOrder): Promise<ExecutionResult>;
+    /** Cancel a pending order. First class, not a modify with a special case. */
+    cancelOrder(terminalId: string, ticket: number, options: Keyed): Promise<ExecutionResult>;
+    /** Move a position's stop loss, take profit, or both. At least one is required. */
+    modifyPosition(terminalId: string, ticket: number, change: ModifyPosition): Promise<ExecutionResult>;
+    /** Close a position in full. */
+    closePosition(terminalId: string, ticket: number, options: ClosePosition): Promise<ExecutionResult>;
+    /** Close part of a position: the volume to close, inside the symbol's step. The rest stays. */
+    closePositionPartial(terminalId: string, ticket: number, options: ClosePositionPartial): Promise<ExecutionResult>;
+    /**
+     * Close a position against an opposite one in the same symbol (hedging accounts): the smaller
+     * disappears and the larger is reduced by its volume.
+     */
+    closePositionBy(terminalId: string, ticket: number, options: ClosePositionBy): Promise<ExecutionResult>;
+    /**
+     * Keep the position's stop loss `distance` behind the best price it reaches, only ever tighter.
+     * Setting it again replaces the distance and keeps what the stop has reached.
+     */
+    setTrailingStop(terminalId: string, ticket: number, options: SetTrailingStop): Promise<ExecutionResult>;
+    /** Remove the position's trailing stop. The stop loss stays where the trail left it. */
+    clearTrailingStop(terminalId: string, ticket: number, options: Keyed): Promise<ExecutionResult>;
+    /**
+     * Read the command until it is final, or until `timeoutMs` (30 s unless given), pausing 200 ms
+     * and doubling up to 2 s between reads. Returns the last answer either way: a command still
+     * EXECUTING when the time runs out is reported as it is, not guessed at. **A result that is not
+     * final is never a reason to send again**: an UNKNOWN command may already be a position.
+     */
+    waitFor(commandId: string, options?: WaitFor): Promise<ExecutionResult>;
     /**
      * One command and its result, as the platform has it now. A command of another tenant is not
      * found, never forbidden. Like every method here it resolves to a result and never rejects:

package/dist/execution.js

@@ -1,4 +1,5 @@
-// `client.execution`: placing orders.
+// `client.execution`: placing orders, changing and cancelling them, and changing and closing
+// positions.
 //
 // 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
@@ -57,6 +58,38 @@ function orderBody(order) {
         ...Object.fromEntries(Object.entries(optional).filter(([, v]) => v !== undefined)),
     };
 }
+/** The first pause between reads of a command, doubled each time up to {@link POLL_CAP_MS}. */
+export const POLL_FROM_MS = 200;
+/** The longest pause between two reads of a command. */
+export const POLL_CAP_MS = 2000;
+function ticketOf(name, value) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1) {
+        throw new TypeError(`${name} is a positive whole number, the ticket MT5 gave`);
+    }
+    return value;
+}
+function commentOf(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string")
+        throw new TypeError("comment is a string");
+    if (value.length > 31) {
+        throw new RangeError("comment is at most 31 characters; MT5 would cut a longer one");
+    }
+    return value;
+}
+function present(fields) {
+    return Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== undefined));
+}
+function maybe(name, value) {
+    return value === undefined ? undefined : decimal(name, value);
+}
+function closing(options) {
+    return present({
+        deviation_points: whole("deviationPoints", options.deviationPoints, 0, 2 ** 31 - 1),
+        comment: commentOf(options.comment),
+    });
+}
 /** Order entry for one tenant. Every method resolves to a result; none rejects. */
 export class Execution {
     #client;
@@ -76,6 +109,101 @@ export class Execution {
         const body = orderBody(order);
         return this.#command({ method: "POST", path: `/terminals/${id}/orders`, body, idempotencyKey: key }, key);
     }
+    /**
+     * Amend a pending order's price, stops or expiry; at least one must change. Its volume, side,
+     * type and symbol cannot be amended: cancel it and place another.
+     */
+    async modifyOrder(terminalId, ticket, change) {
+        const expiresAt = change.expiresAt instanceof Date ? change.expiresAt.toISOString() : change.expiresAt;
+        const body = present({
+            price: maybe("price", change.price),
+            stop_limit_price: maybe("stopLimitPrice", change.stopLimitPrice),
+            sl: maybe("sl", change.sl),
+            tp: maybe("tp", change.tp),
+            expires_at: expiresAt,
+        });
+        if (Object.keys(body).length === 0) {
+            throw new TypeError("modifyOrder changes nothing: give a price, stops or an expiry");
+        }
+        return this.#on(terminalId, ticket, "orders", "modify", change, body);
+    }
+    /** Cancel a pending order. First class, not a modify with a special case. */
+    async cancelOrder(terminalId, ticket, options) {
+        return this.#on(terminalId, ticket, "orders", "cancel", options);
+    }
+    /** Move a position's stop loss, take profit, or both. At least one is required. */
+    async modifyPosition(terminalId, ticket, change) {
+        const body = present({ sl: maybe("sl", change.sl), tp: maybe("tp", change.tp) });
+        if (Object.keys(body).length === 0) {
+            throw new TypeError("modifyPosition changes nothing: give sl, tp or both");
+        }
+        return this.#on(terminalId, ticket, "positions", "modify", change, body);
+    }
+    /** Close a position in full. */
+    async closePosition(terminalId, ticket, options) {
+        return this.#on(terminalId, ticket, "positions", "close", options, closing(options));
+    }
+    /** Close part of a position: the volume to close, inside the symbol's step. The rest stays. */
+    async closePositionPartial(terminalId, ticket, options) {
+        const body = { volume: decimal("volume", options.volume), ...closing(options) };
+        return this.#on(terminalId, ticket, "positions", "close-partial", options, body);
+    }
+    /**
+     * Close a position against an opposite one in the same symbol (hedging accounts): the smaller
+     * disappears and the larger is reduced by its volume.
+     */
+    async closePositionBy(terminalId, ticket, options) {
+        const by = ticketOf("byTicket", options.byTicket);
+        if (by === ticket)
+            throw new RangeError("a position cannot be closed by itself");
+        return this.#on(terminalId, ticket, "positions", "close-by", options, { by_ticket: by });
+    }
+    /**
+     * Keep the position's stop loss `distance` behind the best price it reaches, only ever tighter.
+     * Setting it again replaces the distance and keeps what the stop has reached.
+     */
+    async setTrailingStop(terminalId, ticket, options) {
+        const body = { distance: decimal("distance", options.distance) };
+        return this.#on(terminalId, ticket, "positions", "trailing-stop", options, body, "PUT");
+    }
+    /** Remove the position's trailing stop. The stop loss stays where the trail left it. */
+    async clearTrailingStop(terminalId, ticket, options) {
+        return this.#on(terminalId, ticket, "positions", "trailing-stop", options, undefined, "DELETE");
+    }
+    /**
+     * Read the command until it is final, or until `timeoutMs` (30 s unless given), pausing 200 ms
+     * and doubling up to 2 s between reads. Returns the last answer either way: a command still
+     * EXECUTING when the time runs out is reported as it is, not guessed at. **A result that is not
+     * final is never a reason to send again**: an UNKNOWN command may already be a position.
+     */
+    async waitFor(commandId, options = {}) {
+        const timeout = options.timeoutMs ?? 30_000;
+        if (!Number.isFinite(timeout) || timeout < 1 || timeout > 600_000) {
+            throw new RangeError("timeoutMs is 1 to 600,000");
+        }
+        const key = options.idempotencyKey ?? "";
+        let result = await this.getCommand(commandId, key);
+        // DECISION: the time is counted in the pauses the client takes, not on a wall clock, so a
+        // scripted sleep in a test gives the same schedule a caller gets.
+        let waited = 0;
+        let pause = POLL_FROM_MS;
+        while (!result.final && waited < timeout) {
+            const step = Math.min(pause, POLL_CAP_MS, timeout - waited);
+            await this.#client.pause(step);
+            waited += step;
+            pause *= 2;
+            result = await this.getCommand(commandId, key);
+        }
+        return result;
+    }
+    /** One command on an existing order or position: checked, then sent once. */
+    async #on(terminalId, ticket, kind, action, options, body, method = "POST") {
+        const id = uuid("terminalId", terminalId);
+        const number = ticketOf("ticket", ticket);
+        const key = idempotencyKey(options?.idempotencyKey);
+        const path = `/terminals/${id}/${kind}/${String(number)}/${action}`;
+        return this.#command({ method, path, ...(body === undefined ? {} : { body }), idempotencyKey: key }, key);
+    }
     /**
      * One command and its result, as the platform has it now. A command of another tenant is not
      * found, never forbidden. Like every method here it resolves to a result and never rejects: