@tickerall/sdk 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,572 @@
+import { EventEmitter } from 'node:events';
+
+type BrokerName = 'mt4' | 'mt5';
+type OrderSide = 'BUY' | 'SELL';
+type OrderType = 'market' | 'limit' | 'stop';
+type AccountStatusListing = 'PENDING' | 'ACTIVE' | 'COOLED' | 'REJECTED';
+interface SessionStartParams {
+    broker: BrokerName;
+    server: string;
+    account: number | string;
+    password: string;
+}
+interface SessionStartResult {
+    accountId: string;
+    isDemo: boolean;
+    status: 'connected';
+    expiresAt: string;
+}
+/**
+ * An always-hot account that currently has no live connection (it died — e.g.
+ * TickerAll restarted — and needs a credentials refresh). Returned by
+ * `sessions.pendingRearm()`.
+ */
+interface PendingRearmAccount {
+    id: string;
+    broker: BrokerName;
+    server: string;
+    accountNumber: string;
+}
+interface AccountListing {
+    id: string;
+    broker: BrokerName;
+    server: string;
+    accountNumber: string;
+    isDemo: boolean;
+    status: AccountStatusListing;
+    lastHotAt: string | null;
+    createdAt: string;
+}
+interface AccountInfo {
+    name: string;
+    accountType: string;
+    leverage: number;
+    balance: number;
+    brokerName?: string;
+    brokerWebsite?: string;
+    supportEmail?: string;
+    metaQuotesId?: string;
+}
+interface Position {
+    ticket: number;
+    symbol: string;
+    side: OrderSide;
+    volume: number;
+    openTime?: string;
+    entryPrice?: number;
+    stopLoss: number;
+    takeProfit: number;
+    currentPrice?: number;
+    profit?: number;
+    magic: number;
+    comment: string;
+    swap: number;
+    commission: number;
+    lastUpdate?: string;
+}
+interface AccountDetailOnline {
+    id: string;
+    broker: BrokerName;
+    server: string;
+    accountNumber: string;
+    isDemo: boolean;
+    status: 'online';
+    account: AccountInfo | null;
+    positions: Position[];
+}
+interface AccountDetailOffline {
+    id: string;
+    broker: BrokerName;
+    server: string;
+    accountNumber: string;
+    isDemo: boolean;
+    status: 'offline';
+    hint: string;
+}
+type AccountDetail = AccountDetailOnline | AccountDetailOffline;
+interface SymbolsResponse {
+    symbols: string[];
+}
+/** Per-symbol volume constraints for validating an order size before placing.
+ *  `specSource` is `'broker'` when the broker pushed all three volume fields
+ *  (authoritative), else `'derived'` — filled from the SDK's per-category
+ *  Exness defaults, so treat derived specs as best-effort, not authoritative.
+ *  `tradeMode` is MT5's ENUM_SYMBOL_TRADE_MODE when available:
+ *    0=DISABLED, 1=LONGONLY, 2=SHORTONLY, 3=CLOSEONLY, 4=FULL.
+ *  Undefined on MT4 (no equivalent) and on truncated/older-SDK responses.
+ *  `tradeModeSource` is the SDK-authoritative provenance of `tradeMode`,
+ *  mirrors `specSource` semantics for that field specifically. */
+interface SymbolSpec {
+    name: string;
+    volumeMin: number;
+    volumeMax: number;
+    volumeStep: number;
+    specSource: 'broker' | 'derived';
+    tradeMode?: number;
+    tradeModeSource?: 'broker' | 'derived';
+}
+interface SymbolSpecsResponse {
+    specs: SymbolSpec[];
+}
+interface PlaceOrderParams {
+    type: OrderType;
+    symbol: string;
+    side: OrderSide;
+    volume: number;
+    price?: number;
+    stopLoss?: number;
+    takeProfit?: number;
+    comment?: string;
+}
+interface PlaceOrderResult {
+    ticket: number;
+    symbol: string;
+    side: OrderSide;
+    type: OrderType;
+    volume: number;
+    price?: number;
+    stopLoss: number | null;
+    takeProfit: number | null;
+    comment: string | null;
+    status: 'open' | 'pending';
+    timestamp: string;
+}
+interface ClosePositionParams {
+    volume?: number;
+}
+interface ClosePositionResult {
+    ticket: number;
+    symbol: string;
+    side: OrderSide;
+    volume: number;
+    closed: true;
+    timestamp: string;
+}
+interface ModifyPositionParams {
+    stopLoss?: number;
+    takeProfit?: number;
+}
+interface ModifyPositionResult {
+    ticket: number;
+    symbol: string;
+    side: OrderSide;
+    volume: number;
+    stopLoss: number;
+    takeProfit: number;
+    timestamp: string;
+}
+interface RequestOptions {
+    signal?: AbortSignal;
+    timeout?: number;
+}
+interface IdempotentRequestOptions extends RequestOptions {
+    idempotencyKey?: string;
+    /**
+     * Opt a state-changing call into queue-and-replay. Default `false` — a call
+     * that hits a transient connectivity failure (TickerAll momentarily
+     * unreachable) fails fast with a `TickerallServiceUnavailableError` so you
+     * can re-decide with fresh prices.
+     *
+     * When `true`, the call is instead held in an in-order queue and replayed —
+     * with its stable `Idempotency-Key`, so the server dedupes any attempt that
+     * already executed — until it succeeds or `queueMaxMs` elapses. Use this for
+     * orders that aren't price-sensitive (e.g. pending orders, SL/TP edits);
+     * avoid it for market orders, where a delayed fill at a moved price is
+     * usually worse than a fast failure.
+     */
+    queueIfReconnecting?: boolean;
+    /**
+     * Maximum time (ms) a `queueIfReconnecting` call waits across replays before
+     * giving up and rejecting with the transient error. Default 60_000.
+     * Ignored unless `queueIfReconnecting` is `true`.
+     */
+    queueMaxMs?: number;
+}
+/** Connection state of a {@link TickerallStream}. */
+type StreamState = 'connecting' | 'open' | 'reconnecting' | 'closed';
+interface TickerallClientConfig {
+    apiKey: string;
+    baseUrl?: string;
+    streamUrl?: string;
+    timeout?: number;
+    fetch?: typeof globalThis.fetch;
+    userAgent?: string;
+    /**
+     * Called when the client transparently re-arms a kept session (re-supplies
+     * broker credentials because the account went cold — e.g. after an atlas
+     * restart). Observability only; the re-arm + retry happen automatically.
+     */
+    onRearm?: (accountId: string) => void;
+}
+interface TickEvent {
+    type: 'tick';
+    accountId: string;
+    symbol: string;
+    bid: number;
+    ask: number;
+    timestamp: string;
+}
+type PositionEventType = 'position-opened' | 'position-updated' | 'position-closed';
+interface PositionEvent {
+    type: 'position';
+    accountId: string;
+    event: PositionEventType;
+    position: Position;
+}
+interface AccountEvent {
+    type: 'account';
+    accountId: string;
+    snapshot: {
+        group: string;
+        balance: number;
+    };
+}
+interface StreamErrorEvent {
+    message: string;
+    cause?: unknown;
+}
+interface StreamCloseEvent {
+    code: number;
+    reason: string;
+}
+interface StreamReconnectEvent {
+    attempt: number;
+}
+type Timeframe = 'M1' | 'M5' | 'M15' | 'M30' | 'H1' | 'H4' | 'D1' | 'W1' | 'MN1';
+interface CandlesParams {
+    /** Broker-native symbol name, e.g. "BTCUSDm". */
+    symbol: string;
+    /** How many hours of history to return, counted back from now. */
+    hours: number;
+    /** Bar interval. Defaults to "M5" server-side. Coarser timeframes reach further back. */
+    timeframe?: Timeframe;
+}
+interface Candle {
+    /** Bar OPEN time, Unix seconds (UTC). */
+    timestamp: number;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    /** Mirrors close. */
+    bid: number;
+}
+interface CandlesResponse {
+    symbol: string;
+    hours: number;
+    timeframe: Timeframe;
+    candles: Candle[];
+}
+interface HistoryParams {
+    /** Narrow to one broker-native symbol, e.g. "BTCUSDm". */
+    symbol?: string;
+    /** Lower bound on close time — ISO-8601 string, epoch seconds/ms, or a Date. */
+    from?: string | number | Date;
+    /** Upper bound on close time — ISO-8601 string, epoch seconds/ms, or a Date. */
+    to?: string | number | Date;
+    /** Max rows to return (server caps at 5000; defaults to 500). */
+    limit?: number;
+    /**
+     * How long (ms) the server may wait for the broker's login deal-log burst to
+     * settle on a just-warmed account. Pass 0 on a hot poller to skip the wait.
+     */
+    waitMs?: number;
+}
+interface HistoryTrade {
+    /** Opening deal ticket — the round-trip's identity. */
+    ticket: string;
+    symbol: string;
+    side: 'BUY' | 'SELL';
+    volume: number;
+    openPrice: number;
+    closePrice: number;
+    /** ISO-8601 UTC. */
+    openTime: string;
+    /** ISO-8601 UTC. */
+    closeTime: string;
+    /** Realised P/L in account currency; null if the broker didn't report it. */
+    profit: number | null;
+    swap: number;
+    commission: number;
+    stopLoss: number;
+    takeProfit: number;
+    /** Closing deal ticket, or null if the close leg wasn't paired. */
+    closeTicket: string | null;
+    /** True when both legs were paired into a complete round-trip. */
+    complete: boolean;
+}
+interface HistoryResponse {
+    trades: HistoryTrade[];
+    count: number;
+    symbol?: string;
+    from?: string;
+    to?: string;
+    limit: number;
+}
+
+declare class SessionsNamespace {
+    private readonly client;
+    constructor(client: Tickerall);
+    start(params: SessionStartParams, options?: IdempotentRequestOptions): Promise<SessionStartResult>;
+    /**
+     * Start a session AND keep it alive: the broker credentials are cached in
+     * this process's memory (never persisted) so the client transparently
+     * re-arms the account if it later goes cold — e.g. after an atlas restart.
+     * Pair with an always-hot account for a connection that stays up with no
+     * manual reconnect. Call {@link stopKeepAlive} (or {@link end}) to forget
+     * the credentials.
+     */
+    keepAlive(params: SessionStartParams, options?: IdempotentRequestOptions): Promise<SessionStartResult>;
+    /** Stop auto-re-arming an account and drop its cached credentials. */
+    stopKeepAlive(accountId: string): void;
+    /**
+     * Manually re-arm a kept account now (a fresh session.start with the cached
+     * credentials). Normally unnecessary — the client re-arms on demand — but
+     * useful to proactively recover accounts listed by `GET /v1/always-hot/pending`.
+     */
+    rearm(accountId: string): Promise<void>;
+    /**
+     * Always-hot accounts that currently have no live connection — they need a
+     * credentials refresh (e.g. after a TickerAll restart). Poll this after a
+     * suspected outage; the next call or stream reconnect also re-arms them
+     * automatically.
+     */
+    pendingRearm(options?: RequestOptions): Promise<PendingRearmAccount[]>;
+    /**
+     * Re-arm every pending account we hold kept credentials for (the ones we
+     * actually can recover). Returns the account IDs that were re-armed.
+     */
+    rearmPending(options?: RequestOptions): Promise<string[]>;
+    end(accountId: string, options?: RequestOptions): Promise<void>;
+}
+
+declare class AccountsNamespace {
+    private readonly client;
+    constructor(client: Tickerall);
+    list(options?: RequestOptions): Promise<AccountListing[]>;
+    get(accountId: string, options?: RequestOptions): Promise<AccountDetail>;
+    symbols(accountId: string, options?: RequestOptions): Promise<string[]>;
+    /**
+     * Per-symbol volume specs (min / max / step) for this account's tradeable
+     * symbols — use these to check an order volume before placing it. Each spec
+     * carries `specSource`: `'broker'` (the broker pushed it, authoritative) or
+     * `'derived'` (filled from category defaults — best-effort). MT5 only; an
+     * MT4 account returns an empty list.
+     */
+    symbolSpecs(accountId: string, options?: RequestOptions): Promise<SymbolSpec[]>;
+}
+
+declare class OrdersNamespace {
+    private readonly client;
+    constructor(client: Tickerall);
+    place(accountId: string, params: PlaceOrderParams, options?: IdempotentRequestOptions): Promise<PlaceOrderResult>;
+}
+
+declare class PositionsNamespace {
+    private readonly client;
+    constructor(client: Tickerall);
+    close(accountId: string, ticket: number, params?: ClosePositionParams, options?: IdempotentRequestOptions): Promise<ClosePositionResult>;
+    modify(accountId: string, ticket: number, params: ModifyPositionParams, options?: IdempotentRequestOptions): Promise<ModifyPositionResult>;
+}
+
+interface StreamConfig {
+    streamUrl: string;
+    apiKey: string;
+    userAgent: string;
+}
+interface TickerallStreamEvents {
+    tick: (e: TickEvent) => void;
+    position: (e: PositionEvent) => void;
+    account: (e: AccountEvent) => void;
+    error: (e: StreamErrorEvent) => void;
+    close: (e: StreamCloseEvent) => void;
+    reconnect: (e: StreamReconnectEvent) => void;
+    open: () => void;
+}
+declare class TickerallStream extends EventEmitter {
+    private ws;
+    private closedByUser;
+    private state;
+    private beforeResubscribe?;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private heartbeatTimer;
+    private heartbeatTimeoutTimer;
+    private readonly subs;
+    private readonly url;
+    private readonly headers;
+    constructor(url: string, apiKey: string, userAgent: string);
+    on<E extends keyof TickerallStreamEvents>(event: E, listener: TickerallStreamEvents[E]): this;
+    once<E extends keyof TickerallStreamEvents>(event: E, listener: TickerallStreamEvents[E]): this;
+    off<E extends keyof TickerallStreamEvents>(event: E, listener: TickerallStreamEvents[E]): this;
+    connect(): Promise<void>;
+    /**
+     * Internal: callback run after a RECONNECT (not the initial connect), before
+     * subscriptions are re-sent. The SDK wires this to re-arm kept sessions so a
+     * connection transparently survives an atlas restart.
+     */
+    setBeforeResubscribe(cb: () => Promise<void>): void;
+    /**
+     * Current connection state. `'open'` means live; `'reconnecting'` means the
+     * SDK is silently re-establishing the link (idle apps need do nothing).
+     * Queryable any time — never thrown at you.
+     */
+    getState(): StreamState;
+    /** `true` only when the stream is live and ready to receive. */
+    isConnected(): boolean;
+    /**
+     * Resolve once the stream is live (immediately if already open), or reject
+     * after `timeoutMs`. Rejects right away if the stream was closed by the
+     * caller. Handy to gate logic on a confirmed connection without polling.
+     */
+    waitUntilConnected(timeoutMs?: number): Promise<void>;
+    private openOnce;
+    private handleFrame;
+    private startHeartbeat;
+    private clearHeartbeatTimeout;
+    private stopHeartbeat;
+    private forceReconnect;
+    private scheduleReconnect;
+    private resendSubscriptions;
+    private send;
+    subscribeTicks(accountId: string, symbols: string[]): Promise<void>;
+    unsubscribeTicks(accountId: string, symbols: string[]): Promise<void>;
+    subscribePositions(accountId: string): Promise<void>;
+    subscribeAccount(accountId: string): Promise<void>;
+    close(): Promise<void>;
+}
+declare class StreamNamespace {
+    private readonly client;
+    private readonly streamUrl;
+    private readonly apiKey;
+    private readonly userAgent;
+    constructor(client: Tickerall, config: StreamConfig);
+    connect(): Promise<TickerallStream>;
+}
+
+declare class CandlesNamespace {
+    private readonly client;
+    constructor(client: Tickerall);
+    /**
+     * Fetch historical OHLC candles for a symbol from one of your broker
+     * accounts.
+     *
+     * Candles are read from the account's own live broker connection, so pass
+     * the `accountId` of a connected account. Coarser timeframes reach further
+     * back; a single request returns as much history as fits in a few seconds,
+     * so pass a large `hours` and take what comes back. Deep look-backs are
+     * served on an isolated history connection and won't disturb your live tick
+     * stream.
+     *
+     * @example
+     * const bars = await client.candles.get(accountId, { symbol: 'BTCUSDm', hours: 8760, timeframe: 'D1' })
+     */
+    get(accountId: string, params: CandlesParams, options?: RequestOptions): Promise<Candle[]>;
+}
+
+declare class HistoryNamespace {
+    private readonly client;
+    constructor(client: Tickerall);
+    /**
+     * Closed-trade history for one of your broker accounts — executed deals
+     * paired into round-trips, read from the account's own live broker
+     * connection (the equivalent of MT5's history_deals_get for the recent
+     * window).
+     *
+     * `symbol`/`from`/`to`/`limit` FILTER the broker's recent deal log (a few
+     * weeks deep, broker-controlled) plus any closes seen live this session —
+     * they don't fetch deeper than the broker's window. Pass the `accountId` of
+     * a connected account.
+     *
+     * @example
+     * const trades = await client.history.get(accountId, { symbol: 'BTCUSDm', limit: 100 })
+     */
+    get(accountId: string, params?: HistoryParams, options?: RequestOptions): Promise<HistoryTrade[]>;
+}
+
+declare class Tickerall {
+    readonly sessions: SessionsNamespace;
+    readonly accounts: AccountsNamespace;
+    readonly orders: OrdersNamespace;
+    readonly positions: PositionsNamespace;
+    readonly stream: StreamNamespace;
+    readonly candles: CandlesNamespace;
+    readonly history: HistoryNamespace;
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly streamUrl;
+    private readonly timeout;
+    private readonly fetchImpl;
+    private readonly userAgent;
+    private readonly replayQueue;
+    private replayDraining;
+    private readonly keptCreds;
+    private readonly onRearm?;
+    constructor(config: TickerallClientConfig);
+    private requestWithRearm;
+    private requestOnce;
+    private enqueueReplay;
+    private drainReplayQueue;
+}
+
+interface TickerallErrorInit {
+    status: number;
+    code: string;
+    message: string;
+    requestId?: string;
+    details?: unknown;
+    /**
+     * Transient = the request failed because TickerAll was momentarily
+     * unreachable (network blip, deploy, restart) rather than because the
+     * request itself was bad. Safe to retry. Set automatically for
+     * `TickerallServiceUnavailableError`; `false` for every other error.
+     */
+    transient?: boolean;
+}
+declare class TickerallApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly requestId?: string;
+    readonly details?: unknown;
+    /**
+     * `true` when the failure is a momentary connectivity issue that is safe
+     * to retry (see {@link TickerallServiceUnavailableError}). `false` for
+     * application errors (auth, validation, broker rejection, …) that won't
+     * change on retry. Use it to decide whether to back off and try again.
+     */
+    readonly transient: boolean;
+    constructor(init: TickerallErrorInit);
+}
+declare class TickerallAuthError extends TickerallApiError {
+    constructor(init: TickerallErrorInit);
+}
+declare class TickerallForbiddenError extends TickerallApiError {
+    constructor(init: TickerallErrorInit);
+}
+declare class TickerallValidationError extends TickerallApiError {
+    constructor(init: TickerallErrorInit);
+}
+declare class TickerallNotFoundError extends TickerallApiError {
+    constructor(init: TickerallErrorInit);
+}
+declare class TickerallBrokerError extends TickerallApiError {
+    constructor(init: TickerallErrorInit);
+}
+/**
+ * TickerAll was momentarily unreachable — a network blip, a deploy, or the
+ * service restarting. This is NOT your fault and NOT a broker rejection: the
+ * request never reached a verdict, so it's safe to retry. `transient` is
+ * always `true`.
+ *
+ * The SDK throws this for network failures, request timeouts, and bare
+ * 502/503s (and `POOL_SHUTTING_DOWN`). By default a trade fails fast with
+ * this error so you can re-decide with fresh prices; pass
+ * `{ queueIfReconnecting: true }` to instead queue the call and replay it
+ * (with its stable idempotency key, so it can't double-execute) once
+ * connectivity returns.
+ */
+declare class TickerallServiceUnavailableError extends TickerallApiError {
+    constructor(init: TickerallErrorInit);
+}
+
+export { type AccountDetail, type AccountDetailOffline, type AccountDetailOnline, type AccountEvent, type AccountInfo, type AccountListing, type AccountStatusListing, type BrokerName, type Candle, type CandlesParams, type CandlesResponse, type ClosePositionParams, type ClosePositionResult, type HistoryParams, type HistoryResponse, type HistoryTrade, type IdempotentRequestOptions, type ModifyPositionParams, type ModifyPositionResult, type OrderSide, type OrderType, type PendingRearmAccount, type PlaceOrderParams, type PlaceOrderResult, type Position, type PositionEvent, type PositionEventType, type RequestOptions, type SessionStartParams, type SessionStartResult, type StreamCloseEvent, type StreamErrorEvent, type StreamReconnectEvent, type StreamState, type SymbolSpec, type SymbolSpecsResponse, type SymbolsResponse, type TickEvent, Tickerall, TickerallApiError, TickerallAuthError, TickerallBrokerError, type TickerallClientConfig, type TickerallErrorInit, TickerallForbiddenError, TickerallNotFoundError, TickerallServiceUnavailableError, TickerallStream, TickerallValidationError, type Timeframe };