@mfxhub/sdk 0.0.0-stage → 0.1.0

package/dist/generated/api.js

@@ -0,0 +1,5 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export {};

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The MFX Hub TypeScript SDK.
+ *
+ * ```ts
+ * import { MfxClient } from "@mfxhub/sdk";
+ * const client = new MfxClient("https://api.dev.mfxhub.com/v1", keyId, privateKey);
+ * ```
+ */
+export { MfxClient, DEFAULT_READ_RETRIES, DEFAULT_TIMEOUT_MS } from "./client.js";
+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 { 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 { CommandState, ExecutionResult, Reason, Tickets } from "./results.js";
+export { Terminals, isUsable } from "./terminals.js";
+export type { CreateTerminal, PageOptions, Redundancy, Terminal, 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.0";

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * The MFX Hub TypeScript SDK.
+ *
+ * ```ts
+ * import { MfxClient } from "@mfxhub/sdk";
+ * const client = new MfxClient("https://api.dev.mfxhub.com/v1", keyId, privateKey);
+ * ```
+ */
+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 { 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.0";

package/dist/pages.d.ts

@@ -0,0 +1,22 @@
+/** One page, and the cursor for the next. `nextCursor` is null on the last page. */
+export declare class Page<T> implements Iterable<T> {
+    readonly items: readonly T[];
+    readonly nextCursor: string | null;
+    readonly returned: number | null;
+    /**
+     * @param items this page's items
+     * @param nextCursor pass it back as `cursor` for the next page; null on the last
+     * @param returned how many are in THIS page, when the server says. Not a total.
+     */
+    constructor(items: readonly T[], nextCursor: string | null, returned: number | null);
+    /** How many are in this page. Not a total, and never to be shown as one. */
+    get length(): number;
+    [Symbol.iterator](): Iterator<T>;
+}
+/**
+ * The page an answer holds. An empty cursor reads as the last page, because an empty string
+ * passed back as a cursor would fetch the first page again for ever.
+ */
+export declare function pageOf<T>(body: unknown): Page<T>;
+/** Every item of every page, one request a page, following the cursor until it is null. */
+export declare function everyItem<T>(read: (cursor: string | undefined) => Promise<Page<T>>): AsyncGenerator<T, void, undefined>;

package/dist/pages.js

@@ -0,0 +1,46 @@
+// Cursor pagination, in one place.
+//
+// Every list in this API is cursor-paginated, and there is no total, no page number and no offset:
+// the API cannot answer those cheaply, so the SDK follows the cursor and never pretends to know
+// how many there are.
+/** One page, and the cursor for the next. `nextCursor` is null on the last page. */
+export class Page {
+    items;
+    nextCursor;
+    returned;
+    /**
+     * @param items this page's items
+     * @param nextCursor pass it back as `cursor` for the next page; null on the last
+     * @param returned how many are in THIS page, when the server says. Not a total.
+     */
+    constructor(items, nextCursor, returned) {
+        this.items = items;
+        this.nextCursor = nextCursor;
+        this.returned = returned;
+    }
+    /** How many are in this page. Not a total, and never to be shown as one. */
+    get length() {
+        return this.items.length;
+    }
+    [Symbol.iterator]() {
+        return this.items[Symbol.iterator]();
+    }
+}
+/**
+ * The page an answer holds. An empty cursor reads as the last page, because an empty string
+ * passed back as a cursor would fetch the first page again for ever.
+ */
+export function pageOf(body) {
+    const page = (typeof body === "object" && body !== null ? body : {});
+    const cursor = page.next_cursor;
+    return new Page(page.items ?? [], typeof cursor === "string" && cursor !== "" ? cursor : null, typeof page.returned === "number" ? page.returned : null);
+}
+/** Every item of every page, one request a page, following the cursor until it is null. */
+export async function* everyItem(read) {
+    let cursor;
+    do {
+        const page = await read(cursor);
+        yield* page.items;
+        cursor = page.nextCursor ?? undefined;
+    } while (cursor !== undefined);
+}

package/dist/results.d.ts

@@ -0,0 +1,78 @@
+import type { components } from "./generated/api.js";
+/** Where a command is. Final: SUCCEEDED, FAILED, EXPIRED, REJECTED. UNKNOWN is not final. */
+export type CommandState = components["schemas"]["CommandState"];
+/**
+ * Why a command ended as it did: the platform's reasons, and four the SDK concludes itself
+ * (`transport_error`, `timeout`, `refused`, and `maintenance` when the API refuses outright).
+ * A reason the platform adds later arrives in `reasonText` as it was sent, with `reason` null.
+ */
+export type Reason = "success" | "requote" | "instrument_disabled" | "no_liquidity" | "market_closed" | "invalid_stops" | "invalid_volume" | "insufficient_funds" | "trade_disabled" | "rejected_other" | "rate_limited" | "expired" | "unknown" | "maintenance" | "transport_error" | "timeout" | "refused";
+/** MT5 relates one order, one deal and one position per fill; null where MT5 has none yet. */
+export interface Tickets {
+    readonly order: number | null;
+    readonly deal: number | null;
+    readonly position: number | null;
+}
+/**
+ * The whole answer to one execution call. Never thrown, always returned.
+ *
+ * Read `state` first: SUCCEEDED is done; FAILED, EXPIRED and REJECTED did not happen; UNKNOWN may
+ * already be a position and must never be sent again under a new key.
+ */
+export interface ExecutionResult {
+    /** True when the command succeeded. */
+    readonly ok: boolean;
+    /** The key this call was made with, so a retry can reuse it without bookkeeping. */
+    readonly idempotencyKey: string;
+    /** How long the SDK waited, end to end, in milliseconds. Always known. */
+    readonly clientRttMs: number;
+    /** The platform's id for the command. */
+    readonly commandId: string | null;
+    readonly state: CommandState | null;
+    /** True once the platform will not change this answer again. */
+    readonly final: boolean;
+    /** Whether sending the same order again under a NEW key can succeed. False while UNKNOWN. */
+    readonly retryable: boolean;
+    /** The same key with the same body: this is the original command, not a second one. */
+    readonly duplicate: boolean;
+    /** Why it ended as it did; null when the platform gives none, as on a success. */
+    readonly reason: Reason | null;
+    /** The reason exactly as it arrived, including one this SDK version does not know. */
+    readonly reasonText: string | null;
+    /** The trading platform's own return code, and its meaning in words. */
+    readonly mt5Retcode: number | null;
+    readonly retcodeText: string | null;
+    /** The broker's own comment, verbatim. */
+    readonly commentRaw: string | null;
+    /** The terminal's state when the command was answered. */
+    readonly terminalState: string | null;
+    readonly tickets: Tickets;
+    /** The price and volume the broker filled at, as decimal strings. */
+    readonly execPrice: string | null;
+    readonly execVolume: string | null;
+    readonly brokerLatencyMs: number | null;
+    readonly agentLatencyMs: number | null;
+    /** How many times the platform sent it to the broker. */
+    readonly attempts: number;
+    /** The terminal a failover moved this command from, when one did. */
+    readonly reroutedFrom: string | null;
+    /** What the platform or the SDK said when the request was refused outright. */
+    readonly detail: string | null;
+    /** When sending it again can work: a maintenance window's end, where the platform said. */
+    readonly retryAt: Date | null;
+}
+/** A result from a Command or a CommandAccepted body, whichever the call answered with. */
+export declare function fromCommand(body: unknown, idempotencyKey: string, clientRttMs: number): ExecutionResult;
+/** Why the SDK itself concluded a result: no answer, no answer in time, or a refusal. */
+export type Concluded = "transport_error" | "timeout" | "refused" | "rate_limited" | "maintenance";
+/**
+ * A result the SDK concluded itself.
+ *
+ * `mayHaveReached` is for a transport error after the request was sent: the order may be a
+ * position, so the result reads UNKNOWN and is not retryable under a new key. Sending it again
+ * under the SAME key is safe, and answers with the original if it arrived.
+ */
+export declare function concluded(reason: Concluded, idempotencyKey: string, clientRttMs: number, detail: string, options?: {
+    readonly mayHaveReached?: boolean;
+    readonly retryAt?: Date | null;
+}): ExecutionResult;

package/dist/results.js

@@ -0,0 +1,119 @@
+// What an execution call answers, and the reasons it can carry.
+//
+// Execution never throws across this boundary. A transport fault, a timeout, a rate limit and a
+// broker rejection are all results, because a trading loop that has to catch exceptions to find
+// out whether it has a position is a trading loop that will one day place two.
+//
+// UNKNOWN is not a failure and must never be sent again under a new key: the order may have
+// reached the broker and its outcome could not be read. `retryable` is false while a command is
+// UNKNOWN, and that is the flag to act on, never the reason or the state read by hand.
+import { decimalOut } from "./decimals.js";
+const STATES = new Set([
+    "ACCEPTED",
+    "ENQUEUED",
+    "DELIVERED",
+    "EXECUTING",
+    "SUCCEEDED",
+    "FAILED",
+    "EXPIRED",
+    "REJECTED",
+    "UNKNOWN",
+]);
+const FINAL = new Set([
+    "SUCCEEDED",
+    "FAILED",
+    "EXPIRED",
+    "REJECTED",
+]);
+const REASONS = new Set([
+    "success",
+    "requote",
+    "instrument_disabled",
+    "no_liquidity",
+    "market_closed",
+    "invalid_stops",
+    "invalid_volume",
+    "insufficient_funds",
+    "trade_disabled",
+    "rejected_other",
+    "rate_limited",
+    "expired",
+    "unknown",
+    "maintenance",
+    "transport_error",
+    "timeout",
+    "refused",
+]);
+function int(value) {
+    return typeof value === "number" && Number.isInteger(value) ? value : null;
+}
+function text(value) {
+    return typeof value === "string" && value !== "" ? value : null;
+}
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+/** A result from a Command or a CommandAccepted body, whichever the call answered with. */
+export function fromCommand(body, idempotencyKey, clientRttMs) {
+    const raw = record(body);
+    const state = typeof raw.state === "string" && STATES.has(raw.state) ? raw.state : null;
+    const result = record(raw.result);
+    const reasonText = text(result.reason);
+    const tickets = record(result.tickets);
+    return {
+        ok: result.ok === true,
+        idempotencyKey,
+        clientRttMs,
+        commandId: text(raw.command_id),
+        state: state,
+        final: typeof raw.final === "boolean" ? raw.final : state !== null && FINAL.has(state),
+        // Never retryable while the outcome is unread: that is how one fill becomes two. A
+        // maintenance refusal is, whatever the flag says: it was refused before it ran.
+        retryable: (result.retryable === true || reasonText === "maintenance") && state !== "UNKNOWN",
+        duplicate: raw.duplicate === true,
+        reason: reasonText !== null && REASONS.has(reasonText) ? reasonText : null,
+        reasonText,
+        mt5Retcode: int(result.mt5_retcode),
+        retcodeText: text(result.retcode_text),
+        commentRaw: text(result.comment_raw),
+        terminalState: text(result.terminal_state),
+        tickets: {
+            order: int(tickets.order),
+            deal: int(tickets.deal),
+            position: int(tickets.position),
+        },
+        execPrice: decimalOut(result.exec_price),
+        execVolume: decimalOut(result.exec_volume),
+        brokerLatencyMs: int(result.broker_latency_ms),
+        agentLatencyMs: int(result.agent_latency_ms),
+        attempts: int(result.attempts) ?? 0,
+        reroutedFrom: text(result.rerouted_from),
+        detail: null,
+        retryAt: null,
+    };
+}
+/**
+ * A result the SDK concluded itself.
+ *
+ * `mayHaveReached` is for a transport error after the request was sent: the order may be a
+ * position, so the result reads UNKNOWN and is not retryable under a new key. Sending it again
+ * under the SAME key is safe, and answers with the original if it arrived.
+ */
+export function concluded(reason, idempotencyKey, clientRttMs, detail, options = {}) {
+    const reached = reason === "transport_error" && options.mayHaveReached === true;
+    return {
+        ...fromCommand({}, idempotencyKey, clientRttMs),
+        reason,
+        reasonText: reason,
+        // A timeout is never retryable: the order may have been placed. A transport error before
+        // the request left is, a rate limit is, and so is a maintenance refusal once the window ends.
+        retryable: !reached &&
+            (reason === "transport_error" || reason === "rate_limited" || reason === "maintenance"),
+        state: reached ? "UNKNOWN" : null,
+        final: true,
+        detail,
+        retryAt: options.retryAt ?? null,
+    };
+}

package/dist/signing.d.ts

@@ -0,0 +1,34 @@
+import { inspect } from "node:util";
+export declare const KEY_HEADER = "X-MFX-Key";
+export declare const TIMESTAMP_HEADER = "X-MFX-Timestamp";
+export declare const NONCE_HEADER = "X-MFX-Nonce";
+export declare const SIGNATURE_HEADER = "X-MFX-Signature";
+/** A tenant's Ed25519 private key, which renders as `***` wherever it could be printed. */
+export declare class SigningKey {
+    #private;
+    /** Accepts PEM, the base64 of the 32 raw bytes, the bytes themselves, or another SigningKey. */
+    constructor(key: string | Uint8Array | SigningKey);
+    /** The base64 signature of `message`. */
+    sign(message: Uint8Array): string;
+    toString(): string;
+    toJSON(): string;
+    [inspect.custom](): string;
+}
+/** The exact bytes a request's signature covers. Refuses a nonce that could move the lines. */
+export declare function signingMessage(timestamp: string, nonce: string, method: string, pathWithQuery: string, body: Uint8Array): Uint8Array;
+/** Makes the four headers for one request, with a fresh timestamp and nonce each time. */
+export declare class RequestSigner {
+    #private;
+    readonly keyId: string;
+    private readonly clock;
+    private readonly nonce;
+    /**
+     * @param keyId the key's id, safe to log
+     * @param key the private key
+     * @param clock milliseconds since the epoch; replaceable in tests
+     * @param nonce a fresh nonce; replaceable in tests
+     */
+    constructor(keyId: string, key: string | Uint8Array | SigningKey, clock?: () => number, nonce?: () => string);
+    /** The headers for one request: the stream's upgrade is signed through here too. */
+    headersFor(method: string, pathWithQuery: string, body?: Uint8Array): Record<string, string>;
+}

package/dist/signing.js

@@ -0,0 +1,103 @@
+/**
+ * The four headers every MFX Hub request carries, and the key that makes them.
+ *
+ * A request is signed, not carrying a token: `X-MFX-Key` names the key, `X-MFX-Timestamp` and
+ * `X-MFX-Nonce` make each request usable once, and `X-MFX-Signature` is an Ed25519 signature over
+ *
+ *     timestamp_ms \n nonce \n METHOD \n path_with_query \n sha256_hex(body)
+ *
+ * base64-encoded. The timestamp is epoch milliseconds and must be within 30 s of the server's
+ * clock; the nonce is unique per key for five minutes, so a retry is always signed again.
+ *
+ * The private key is shown once when the key is issued and the platform never stores it. A
+ * {@link SigningKey} prints as `***` everywhere it could be printed, so it cannot reach a log.
+ */
+import { createHash, createPrivateKey, randomBytes, sign } from "node:crypto";
+import { inspect } from "node:util";
+export const KEY_HEADER = "X-MFX-Key";
+export const TIMESTAMP_HEADER = "X-MFX-Timestamp";
+export const NONCE_HEADER = "X-MFX-Nonce";
+export const SIGNATURE_HEADER = "X-MFX-Signature";
+/** What the platform accepts as a nonce: it is a line of the signed message. */
+const NONCE = /^[A-Za-z0-9_-]{16,64}$/;
+/** PKCS#8 wrapping for a raw 32-byte Ed25519 private key. */
+const PKCS8_ED25519_PREFIX = Buffer.from("302e020100300506032b657004220420", "hex");
+const SEED_BYTES = 32;
+function load(material) {
+    const text = typeof material === "string" ? material.trim() : null;
+    if (text?.startsWith("-----BEGIN")) {
+        const key = createPrivateKey(text);
+        if (key.asymmetricKeyType !== "ed25519") {
+            throw new TypeError(`an MFX Hub key is Ed25519, not ${String(key.asymmetricKeyType)}`);
+        }
+        return key;
+    }
+    const raw = text === null ? Buffer.from(material) : Buffer.from(text, "base64");
+    if (raw.length !== SEED_BYTES || (text !== null && raw.toString("base64") !== text)) {
+        throw new TypeError("a signing key is a PEM private key, or the base64 of its 32 raw bytes, or those bytes");
+    }
+    return createPrivateKey({
+        key: Buffer.concat([PKCS8_ED25519_PREFIX, raw]),
+        format: "der",
+        type: "pkcs8",
+    });
+}
+/** A tenant's Ed25519 private key, which renders as `***` wherever it could be printed. */
+export class SigningKey {
+    #key;
+    /** Accepts PEM, the base64 of the 32 raw bytes, the bytes themselves, or another SigningKey. */
+    constructor(key) {
+        this.#key = key instanceof SigningKey ? key.#key : load(key);
+    }
+    /** The base64 signature of `message`. */
+    sign(message) {
+        return sign(null, message, this.#key).toString("base64");
+    }
+    toString() {
+        return "SigningKey(***)";
+    }
+    toJSON() {
+        return "***";
+    }
+    [inspect.custom]() {
+        return "SigningKey(***)";
+    }
+}
+/** The exact bytes a request's signature covers. Refuses a nonce that could move the lines. */
+export function signingMessage(timestamp, nonce, method, pathWithQuery, body) {
+    if (!NONCE.test(nonce)) {
+        throw new RangeError(`a nonce is 16-64 characters of A-Z a-z 0-9 _ -; got ${nonce.length} characters`);
+    }
+    const digest = createHash("sha256").update(body).digest("hex");
+    return Buffer.from([timestamp, nonce, method.toUpperCase(), pathWithQuery, digest].join("\n"));
+}
+/** Makes the four headers for one request, with a fresh timestamp and nonce each time. */
+export class RequestSigner {
+    keyId;
+    clock;
+    nonce;
+    /**
+     * @param keyId the key's id, safe to log
+     * @param key the private key
+     * @param clock milliseconds since the epoch; replaceable in tests
+     * @param nonce a fresh nonce; replaceable in tests
+     */
+    constructor(keyId, key, clock = Date.now, nonce = () => randomBytes(16).toString("base64url")) {
+        this.keyId = keyId;
+        this.clock = clock;
+        this.nonce = nonce;
+        this.#key = new SigningKey(key);
+    }
+    #key;
+    /** The headers for one request: the stream's upgrade is signed through here too. */
+    headersFor(method, pathWithQuery, body = new Uint8Array()) {
+        const timestamp = String(Math.trunc(this.clock()));
+        const nonce = this.nonce();
+        return {
+            [KEY_HEADER]: this.keyId,
+            [TIMESTAMP_HEADER]: timestamp,
+            [NONCE_HEADER]: nonce,
+            [SIGNATURE_HEADER]: this.#key.sign(signingMessage(timestamp, nonce, method, pathWithQuery, body)),
+        };
+    }
+}

package/dist/stream.d.ts

@@ -0,0 +1,139 @@
+import type { MfxClient } from "./client.js";
+import { MfxError } from "./errors.js";
+/** The server says why it hung up. 4001 is the one reconnecting cannot fix. */
+export declare const CLOSE_REAUTHENTICATE = 4001;
+export declare const CLOSE_SLOW_CONSUMER = 4008;
+export declare const CLOSE_LIFETIME = 4009;
+/** The timeframes closed candles are published for. */
+export type Timeframe = "M1" | "M5" | "M15" | "M30" | "H1" | "H4" | "D1" | "W1" | "MN1";
+/** Builds the channel keys the platform accepts, from ids rather than names. */
+export declare const Channel: {
+    /** Every platform event for this tenant. */
+    readonly events: "events";
+    /** Ticks for one symbol on one server, in the broker's own name for it. */
+    readonly md: (serverId: string, symbol: string) => string;
+    /** Closed candles. Only closed ones are published; a forming candle is not a fact yet. */
+    readonly candles: (serverId: string, symbol: string, timeframe: Timeframe) => string;
+    /** Execution results for one terminal: where a command id is finally answered. */
+    readonly results: (terminalId: string) => string;
+    /** One terminal's live account: a snapshot, then marks. */
+    readonly account: (terminalId: string) => string;
+    /** What the tenant's own expert advisor on this terminal writes. Needs `ea:read`. */
+    readonly ea: (terminalId: string) => string;
+    /** The symbol's order book, whole, each time it changes. */
+    readonly book: (serverId: string, symbol: string) => string;
+};
+/** The connection ended. `code` is the WebSocket close code, `reason` the server's words. */
+export declare class StreamClosed extends MfxError {
+    readonly code: number;
+    readonly reason: string;
+    name: string;
+    constructor(code: number, reason?: string);
+}
+/** One message on one channel. */
+export declare class StreamMessage {
+    readonly channel: string;
+    /** Increases per channel; a jump is counted in `stats.dropped`. */
+    readonly seq: number | null;
+    /** The event type on `events` and `results` (`command.completed`); null on a tick or candle. */
+    readonly type: string | null;
+    readonly data: Readonly<Record<string, unknown>>;
+    /** `account:` only: the seq of the snapshot this message applies to. */
+    readonly base: number | null;
+    constructor(channel: string, 
+    /** Increases per channel; a jump is counted in `stats.dropped`. */
+    seq: number | null, 
+    /** The event type on `events` and `results` (`command.completed`); null on a tick or candle. */
+    type: string | null, data: Readonly<Record<string, unknown>>, 
+    /** `account:` only: the seq of the snapshot this message applies to. */
+    base?: number | null);
+}
+/** The position asked for is older than the replay window: read the current state over REST. */
+export declare class Resync {
+    readonly channel: string;
+    constructor(channel: string);
+}
+/**
+ * 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 declare class ChannelRefused {
+    readonly channel: string;
+    /** The platform's own code: `not_found`, `forbidden`, `not_subscribed`. */
+    readonly code: string;
+    readonly message: string;
+    readonly details: Readonly<Record<string, unknown>>;
+    constructor(channel: string, 
+    /** The platform's own code: `not_found`, `forbidden`, `not_subscribed`. */
+    code: string, message: string, details?: Readonly<Record<string, unknown>>);
+}
+/** What the stream delivers. Resync and ChannelRefused are delivered, not thrown. */
+export type StreamEvent = StreamMessage | Resync | ChannelRefused;
+/** What the stream missed and how often it had to come back. */
+export interface StreamStats {
+    /** Connections opened after the first one. */
+    readonly reconnects: number;
+    /** Messages the sequence numbers prove were not delivered, over every channel. */
+    readonly dropped: number;
+    /** Channels told to resync because the replay window had passed. */
+    readonly resyncs: number;
+    /** Times the server closed the stream for falling behind (4008). */
+    readonly slowConsumerDrops: number;
+    /** Times the 24-hour connection lifetime was reached (4009). Expected, not a fault. */
+    readonly lifetimeReconnects: number;
+    /** Channels the platform refused. Each cost its own channel and nothing else. */
+    readonly refused: number;
+}
+/** What this module needs of a WebSocket, and nothing more. */
+export interface StreamConnection {
+    send(text: string): Promise<void>;
+    /** The next frame; rejects with StreamClosed once the connection has ended. */
+    recv(): Promise<string>;
+    close(): Promise<void>;
+}
+/** Opens one connection with the signed upgrade headers. */
+export type Connector = (url: string, headers: Readonly<Record<string, string>>) => Promise<StreamConnection>;
+/** What {@link MfxClient.stream} takes. */
+export interface StreamOptions {
+    /** Replaces the transport; a test drives reconnects with it. */
+    readonly connect?: Connector;
+    /** The stream's address; derived from the client's base URL by default. */
+    readonly url?: string;
+    /** Stop after this many reconnects; unlimited by default. */
+    readonly maxReconnects?: number;
+}
+/** The default transport, over `ws`, with backpressure: the socket pauses while frames wait. */
+export declare const wsConnector: Connector;
+/** The stream's address beside the REST base: `api.dev.mfxhub.com/v1` is `ws.dev.mfxhub.com/v1/stream`. */
+export declare function streamUrl(baseUrl: string): string;
+/** The multiplexed stream. Opened by `await client.stream()`; closed by `close()`. */
+export declare class MfxStream implements AsyncIterable<StreamEvent> {
+    #private;
+    /** Use {@link MfxClient.stream}. */
+    constructor(client: MfxClient, options?: StreamOptions);
+    /** What has been missed so far. A snapshot; it never changes under the caller. */
+    get stats(): StreamStats;
+    /** The channels currently subscribed, in the order they were asked for. */
+    get channels(): readonly string[];
+    /** Opens the connection. {@link MfxClient.stream} does this for you. */
+    open(): Promise<this>;
+    /** Subscribe to one channel. Subscribing twice is not an error. */
+    subscribe(channel: string): Promise<void>;
+    /**
+     * 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.
+     */
+    resume(channel: string): Promise<void>;
+    /** Stop watching a channel, and stop subscribing to it again after a reconnect. */
+    unsubscribe(channel: string): Promise<void>;
+    /** Close the connection, if one is open. */
+    close(): Promise<void>;
+    [Symbol.asyncIterator](): AsyncGenerator<StreamEvent, void, undefined>;
+    /**
+     * 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.
+     */
+    next(): Promise<StreamEvent | null>;
+    toString(): string;
+}