@zeitvu97/cms-sdk 0.1.0

package/dist/core/ws/ws.constants.d.ts

@@ -0,0 +1,246 @@
+/**
+ * WebSocket-layer defaults + protocol constants.
+ *
+ * Pattern (per FE coding rules §1.5):
+ *   `export const X = { FOO: 'foo', BAR: 'bar' } as const;`
+ *   `export type XKey = (typeof X)[keyof typeof X];`
+ *
+ * See `eaera-docs/cbs/eaera-cms/docs/eaera-cms-websocket-integration-guide.md`
+ * for the wire protocol this client implements.
+ */
+/**
+ * Re-export the MT5 domain constants so WS consumers can grab the server
+ * name + interval enum from the same place they import the topic builders.
+ */
+export { MT5_INTERVAL, MT5_SERVER_NAME } from '../../common/constants/mt5.constant';
+export type { MT5Interval, MT5ServerName } from '../../common/constants/mt5.constant';
+/** Lifecycle states surfaced by `IWsClient.connectionState`. */
+export declare const WS_CONNECTION_STATE: {
+    readonly IDLE: "idle";
+    readonly OPENING: "opening";
+    readonly AUTHENTICATING: "authenticating";
+    readonly OPEN: "open";
+    readonly RECONNECTING: "reconnecting";
+    readonly CLOSED: "closed";
+};
+export type WsConnectionState = (typeof WS_CONNECTION_STATE)[keyof typeof WS_CONNECTION_STATE];
+/**
+ * WebSocket close codes. `NORMAL` is the only one the client sends; the
+ * rest mirror what the CMS server uses (see FEAT-010 guide §3).
+ */
+export declare const WS_CLOSE_CODE: {
+    /** RFC 6455 — clean shutdown (e.g. user logout). */
+    readonly NORMAL: 1000;
+    /** RFC 6455 — `invalid_token` / `token_expired` / `auth_timeout`. */
+    readonly POLICY_VIOLATION: 1008;
+    /** RFC 6455 — `service_unavailable` (token service not configured). */
+    readonly INTERNAL_ERROR: 1011;
+    /** RFC 6455 — graceful server shutdown. */
+    readonly TRY_AGAIN_LATER: 1013;
+    /**
+     * Non-standard — client-side deadline: server did not reply to `auth`
+     * within `WS_AUTH_TIMEOUT_MS`. Closes the socket so the consumer can
+     * react.
+     */
+    readonly CLIENT_AUTH_TIMEOUT: 4000;
+};
+export type WsCloseCode = (typeof WS_CLOSE_CODE)[keyof typeof WS_CLOSE_CODE];
+/** Server-emitted error codes during the `auth` handshake / mid-session (ws-guide §3.4). */
+export declare const WS_AUTH_ERROR_CODE: {
+    readonly INVALID_TOKEN: "invalid_token";
+    readonly TOKEN_EXPIRED: "token_expired";
+    readonly AUTH_TIMEOUT: "auth_timeout";
+    readonly INVALID_MESSAGE: "invalid_message";
+    readonly SERVICE_UNAVAILABLE: "service_unavailable";
+};
+export type WsAuthErrorCode = (typeof WS_AUTH_ERROR_CODE)[keyof typeof WS_AUTH_ERROR_CODE];
+/**
+ * Close-frame reason strings (ws-guide §4.1). These accompany the RFC 6455
+ * close codes in `WS_CLOSE_CODE` — they are NOT auth error codes. Surfaced so
+ * consumers can match `CloseEvent.reason` against stable strings.
+ */
+export declare const WS_CLOSE_REASON: {
+    readonly NORMAL: "normal";
+    readonly INVALID_TOKEN: "invalid_token";
+    readonly TOKEN_EXPIRED: "token_expired";
+    readonly AUTH_TIMEOUT: "auth_timeout";
+    readonly PING_TIMEOUT: "ping_timeout";
+    readonly AUTH_REQUIRED: "auth required";
+    readonly AUTH_SERVICE_UNAVAILABLE: "auth service unavailable";
+    readonly SERVER_SHUTTING_DOWN: "server shutting down";
+};
+export type WsCloseReason = (typeof WS_CLOSE_REASON)[keyof typeof WS_CLOSE_REASON];
+/** Server-emitted error codes on the action invocation path (FEAT-008). */
+/** Accepted-stage error codes — returned on `action_accepted` (ws-guide §9.3). */
+export declare const WS_ACTION_ACCEPTED_ERROR_CODE: {
+    readonly VALIDATION_ERROR: "validation_error";
+    readonly NOT_FOUND: "not_found";
+    readonly PERMISSION_DENIED: "permission_denied";
+    readonly DUPLICATE: "duplicate";
+    readonly INTERNAL_ERROR: "internal_error";
+    readonly CONFIGURATION_ERROR: "configuration_error";
+};
+export type WsActionAcceptedErrorCode = (typeof WS_ACTION_ACCEPTED_ERROR_CODE)[keyof typeof WS_ACTION_ACCEPTED_ERROR_CODE];
+/** Result-stage error codes — returned on `action_result` (ws-guide §9.4). */
+export declare const WS_ACTION_RESULT_ERROR_CODE: {
+    readonly TIMEOUT: "timeout";
+};
+export type WsActionResultErrorCode = (typeof WS_ACTION_RESULT_ERROR_CODE)[keyof typeof WS_ACTION_RESULT_ERROR_CODE];
+/**
+ * All action error codes — union of the accepted-stage and result-stage maps
+ * (ws-guide §9.3 + §9.4). Kept for back-compat with consumers that do not yet
+ * distinguish the stage; prefer the stage-specific maps above for new code.
+ */
+export declare const WS_ACTION_ERROR_CODE: {
+    readonly TIMEOUT: "timeout";
+    readonly VALIDATION_ERROR: "validation_error";
+    readonly NOT_FOUND: "not_found";
+    readonly PERMISSION_DENIED: "permission_denied";
+    readonly DUPLICATE: "duplicate";
+    readonly INTERNAL_ERROR: "internal_error";
+    readonly CONFIGURATION_ERROR: "configuration_error";
+};
+export type WsActionErrorCode = (typeof WS_ACTION_ERROR_CODE)[keyof typeof WS_ACTION_ERROR_CODE];
+/**
+ * Wire `type` field for every server→client and client→server message.
+ *
+ * TypeScript discriminated unions require the `type` field to be a string
+ * literal (not a const reference) on each interface — so these constants are
+ * used for **runtime comparisons** (`switch (msg.type)`) and the interfaces
+ * in `ws.type.ts` keep their literal `type: '…'` annotations for narrowing.
+ */
+export declare const WS_MESSAGE_TYPE: {
+    readonly AUTH_OK: "auth_ok";
+    readonly AUTH_FAIL: "auth_fail";
+    readonly AUTH_EXPIRED: "auth_expired";
+    readonly SUB_OK: "sub_ok";
+    readonly SUB_ERROR: "sub_error";
+    readonly UNSUB_OK: "unsub_ok";
+    readonly PING: "ping";
+    readonly EVENT: "event";
+    readonly ACTION_ACCEPTED: "action_accepted";
+    readonly ACTION_RESULT: "action_result";
+    readonly ERROR: "error";
+    readonly ADMIN_DISCONNECT: "admin_disconnect";
+    readonly AUTH: "auth";
+    readonly SUBSCRIBE: "subscribe";
+    readonly UNSUBSCRIBE: "unsubscribe";
+    readonly UNSUBSCRIBE_ALL: "unsubscribe_all";
+    readonly PONG: "pong";
+    readonly ACTION: "action";
+    readonly FETCH_RESULT: "fetch_result";
+};
+export type WsMessageType = (typeof WS_MESSAGE_TYPE)[keyof typeof WS_MESSAGE_TYPE];
+/**
+ * Built-in topic namespaces (guide §5.4). Server-side permissions are
+ * enforced (`risk:*` requires `content:read`, `mt5:*` requires `mt5:viewer`,
+ * etc.). Use these as the first segment of every topic you publish /
+ * subscribe to.
+ */
+export declare const WS_TOPIC_NAMESPACE: {
+    readonly RISK: "risk";
+    readonly MT5: "mt5";
+    readonly SYMBOL: "symbol";
+    readonly ACCOUNT: "account";
+    readonly USER: "user";
+    readonly STREAM: "stream";
+    readonly ADMIN: "admin";
+};
+export type WsTopicNamespace = (typeof WS_TOPIC_NAMESPACE)[keyof typeof WS_TOPIC_NAMESPACE];
+/**
+ * Canonical topic strings for the built-in namespaces. The server-side
+ * authz pipeline (FEAT-011) checks the prefix against the user's effective
+ * permissions.
+ *
+ * MT5 topics must be built with `mt5Topic(server, eventType)` — the server
+ * segment must match `MT5_SERVER_NAME` exactly (including spaces).
+ */
+export declare const WS_TOPIC: {
+    readonly RISK_RULES: "risk:rules";
+    readonly RISK_EXECUTIONS: "risk:executions";
+};
+export type WsTopic = (typeof WS_TOPIC)[keyof typeof WS_TOPIC];
+/** MT5 event types — third segment of `mt5:events:{server}:{event_type}`. */
+export declare const WS_MT5_EVENT_TYPE: {
+    readonly TICK: "tick";
+    readonly ORDER: "order";
+    readonly POSITION: "position";
+    readonly STATEMENT: "statement";
+    readonly DEAL: "deal";
+};
+export type WsMt5EventType = (typeof WS_MT5_EVENT_TYPE)[keyof typeof WS_MT5_EVENT_TYPE];
+/**
+ * Build an MT5 topic for a specific server + event type. The server segment
+ * MUST match `MT5_SERVER_NAME` exactly (including spaces).
+ */
+export declare const mt5Topic: (serverName: string, eventType: WsMt5EventType) => string;
+/**
+ * Build a per-account state topic: `account:<Mt5Account.uuid>`.
+ * Subscribe with the account's UUID (NOT the numeric login) [ws§7.4, api-inventory §9.9].
+ */
+export declare const accountTopic: (accountUuid: string) => string;
+/**
+ * Build a per-symbol tick topic: `symbol:<server>:<SYMBOL>`.
+ * The preferred live-tick path for charts (one topic per (server, symbol) isolates
+ * per-connection cost to one symbol's tick rate) [ws§7.3, api-inventory §9.3].
+ */
+export declare const symbolTopic: (serverName: string, symbol: string) => string;
+/**
+ * Build a user-scoped notification topic: `user:<id>` [ws§5].
+ */
+export declare const userTopic: (userId: number | string) => string;
+/**
+ * Build a stream-processor output topic: `stream:<id>` [ws§5].
+ */
+export declare const streamTopic: (streamId: string) => string;
+/**
+ * Build an admin topic: `admin:<name>` [ws§5].
+ */
+export declare const adminTopic: (name: string) => string;
+/** Hard cap on topics per connection (server-side default). */
+export declare const WS_MAX_SUBSCRIPTIONS = 50;
+/** Reconnect backoff schedule (matches the integration guide's recommendation). */
+export declare const WS_RECONNECT_INITIAL_MS = 1000;
+export declare const WS_RECONNECT_MAX_MS = 30000;
+/** Random jitter added to each reconnect delay, in milliseconds. */
+export declare const WS_RECONNECT_JITTER_MS = 250;
+/** Server-driven ping interval (server sends `ping` every N seconds). */
+export declare const WS_PING_INTERVAL_MS = 30000;
+/**
+ * Client-side ping-watchdog multiplier. The watchdog force-closes the socket
+ * after `pingIntervalMs * WS_PING_WATCHDOG_FACTOR` without a server `ping`,
+ * catching half-open (sleep / NAT-timeout) connections before the server's
+ * own 2-missed-pong timeout (ws-guide §8).
+ */
+export declare const WS_PING_WATCHDOG_FACTOR = 1.5;
+/** Floor for the watchdog interval check (never probe more often than this). */
+export declare const WS_PING_WATCHDOG_CHECK_MS = 15000;
+/**
+ * Max reconnect attempts before the client transitions to terminal `CLOSED`
+ * (ws-guide §10). Prevents an infinite `RECONNECTING` loop on a prolonged
+ * outage so consumers (e.g. the Nuxt recovery plugin) can surface a
+ * "connection lost" notification instead of retrying silently forever.
+ */
+export declare const WS_MAX_RECONNECT_ATTEMPTS = 10;
+/** Window in which the server expects the first `auth` message. */
+export declare const WS_AUTH_TIMEOUT_MS = 10000;
+/**
+ * Server-side TTL for an in-flight `action` after disconnect. The client
+ * uses `fetch_result` within this window to recover a missed `action_result`.
+ */
+export declare const WS_ACTION_RESULT_TTL_MS: number;
+/**
+ * MT5 broker retcodes surfaced through `action_result.output.data.retcode`.
+ * Source: eaera-docs §7.5 / ws-guide §12.6.
+ */
+export declare const MT5_RETCODE: {
+    readonly REQ_REJECT: 10004;
+    readonly REQ_CANCELLED: 10006;
+    readonly PRICE_OFF_QUOTES: 10016;
+    readonly REQUEST_CHANGED: 10024;
+    readonly PRICE_OFF: 10030;
+    readonly CONNECTION_LOST: 10031;
+    readonly NETWORK_ERROR: 10032;
+};
+export type Mt5Retcode = (typeof MT5_RETCODE)[keyof typeof MT5_RETCODE];
+//# sourceMappingURL=ws.constants.d.ts.map

package/dist/core/ws/ws.constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws.constants.d.ts","sourceRoot":"","sources":["../../../src/core/ws/ws.constants.ts"],"names":[],"mappings":"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"}

package/dist/core/ws/ws.events.d.ts

@@ -0,0 +1,264 @@
+import { MT5DealEntry, MT5TradeSide } from '../../common/constants/mt5.constant';
+/**
+ * `data.event` discriminator values emitted by the backend. Not every payload
+ * carries one (e.g. the `tick` topic omits it — see {@link ITickEvent}); those
+ * are dispatched on `topic` instead. Kept here so consumers can route without
+ * hard-coding string literals.
+ */
+export declare const WS_EVENT_NAME: {
+    readonly ACCOUNT_STATE: "account_state";
+    readonly POSITION: "position";
+    readonly ORDER: "order";
+    readonly DEAL: "deal";
+    readonly SYMBOL_TICK: "symbol_tick";
+    readonly LAST_TICK: "last_tick";
+};
+export type WsEventName = (typeof WS_EVENT_NAME)[keyof typeof WS_EVENT_NAME];
+/**
+ * Per-position row embedded inside an {@link IAccountStateEvent} snapshot
+ * (ws-guide §7.4.1). The `server`, `login`, and `timestampServer` columns that
+ * live on the parent envelope are stripped here by the CMS `account_bridge`.
+ *
+ * Note the `action` divergence: this snapshot uses the **numeric** MT5 type
+ * (`0` = Buy, `1` = Sell), whereas the live {@link IPositionEvent} /
+ * {@link IDealEvent} use the decoded **string** (`'BUY' | 'SELL'`). Consumers
+ * that merge both feeds must coerce once at their boundary.
+ */
+export interface IAccountStatePosition {
+    /** MT5 `Position` ticket — stable identity. */
+    positionId: number;
+    symbol: string;
+    /** `0` = Buy, `1` = Sell (numeric — see interface note above). */
+    action: number;
+    /** Initial open lot size. */
+    volume: number;
+    /** Cumulative volume already closed by partial fills. */
+    volumeClosed: number;
+    /** Still-open size (`volume − volumeClosed`). */
+    volumeRemaining: number;
+    /** Current market price at `wave_ts`. */
+    price: number;
+    /** Entry / open price. */
+    pricePosition: number;
+    /** Stop-loss price; `0` if not set. */
+    priceSl: number;
+    /** Take-profit price; `0` if not set. */
+    priceTp: number;
+    /** Gross floating PnL (before swap/commission). */
+    profit: number;
+    /** Net floating PnL (after swap/commission/fee). */
+    netProfit: number;
+    /**
+     * Swap/rollover accumulated on the open position. The BE emits this on the
+     * wire but the ws-guide §7.4.1 field list has not been updated to include
+     * it — optional so consumers on older BE envs stay honest.
+     */
+    swap?: number;
+    /** Broker open-time, unix-**millisecond** tick. */
+    timestampOpen: number;
+    /** Wave snapshot time (ISO-8601). */
+    timestamp: string;
+    /** Broker comment (≤ 31 chars). */
+    comment: string;
+}
+/**
+ * Per-order row embedded inside an {@link IAccountStateEvent} snapshot
+ * (ws-guide §7.4). The pending orders the account holds at `wave_ts`. The
+ * `server` / `login` columns that live on the parent envelope are stripped
+ * here by the CMS `account_bridge`, mirroring {@link IAccountStatePosition}.
+ */
+export interface IAccountStateOrder {
+    /** MT5 `Order` ticket — stable identity. */
+    orderId: number;
+    symbol: string;
+    /** Initial requested lot size. */
+    volume: number;
+    /** Limit / stop trigger price. */
+    price: number;
+    /** Order stop-loss level; `0` if not set. */
+    priceSl: number;
+    /** Order take-profit level; `0` if not set. */
+    priceTp: number;
+    /** Raw MT5 integer code; `orderTypeStr` is the decoded form. */
+    orderType: number;
+    /** Decoded order type, e.g. `'BUY_LIMIT' | 'SELL_STOP' | …`. */
+    orderTypeStr: string;
+    /** Raw MT5 integer state code; `stateStr` is the decoded form. */
+    state: number;
+    /** `PLACED` | `STARTED` | … (snapshot rows are pending). */
+    stateStr: string;
+    /** `'DAY' | 'GTC' | …`. */
+    duration: string;
+    /** Setup time, unix-**millisecond** integer. */
+    timestampSetup: number;
+    /** Wave snapshot time (ISO-8601). */
+    timestamp: string;
+    /** Broker comment (≤ 31 chars). */
+    comment: string;
+}
+/**
+ * Aggregate account-state payload delivered on topic `account:<Mt5Account.uuid>`
+ * (ws-guide §7.4). Carries the balance/equity/margin summary **and** the
+ * authoritative open-positions + pending-orders lists. This is the camelCase
+ * form the SDK hands to `onEvent` handlers — consumers no longer need a
+ * `toAccountState` adapter.
+ */
+export interface IAccountStateEvent {
+    event: typeof WS_EVENT_NAME.ACCOUNT_STATE;
+    /** `Mt5Account.uuid` — matches the topic suffix. */
+    accountUuid: string;
+    server: string;
+    login: number;
+    /** Statement wave's `wave_ts` (not the publish time). */
+    timestamp: string;
+    balance: number;
+    equity: number;
+    /** Used margin (in use by open positions). */
+    margin: number;
+    /** `equity − margin`. */
+    marginFree: number;
+    /** `equity / margin × 100` (percentage). */
+    marginLevel: number;
+    /** Closed-trade PnL. */
+    profit: number;
+    /** Unrealised PnL of all open positions. */
+    floating: number;
+    /** Wave-snapshot open-position count (should equal `positions.length`). */
+    openPositions: number;
+    /** Wave-snapshot pending-order count (should equal `orders.length`). */
+    pendingOrders: number;
+    positions: IAccountStatePosition[];
+    /** Authoritative pending-orders list at `wave_ts`. */
+    orders: IAccountStateOrder[];
+    currency: string;
+    currencyDigits: number;
+    group: string;
+    leverage: number;
+    publisher: string;
+}
+/** Live position event (Appendix A.3, topic `mt5:events:<server>:position`). */
+export interface IPositionEvent {
+    event: typeof WS_EVENT_NAME.POSITION;
+    eventId: string;
+    server: string;
+    login: number;
+    positionId: number;
+    symbol: string;
+    action: MT5TradeSide;
+    volume: number;
+    volumeClosed: number;
+    volumeRemaining: number;
+    price: number | null;
+    pricePosition: number;
+    priceSl: number | null;
+    priceTp: number | null;
+    profit: number;
+    netProfit: number;
+    /** Swap/rollover — the wire key is `swap`. */
+    swap: number;
+    /** @deprecated Legacy key — the BE now emits `swap`. Optional for consumers still on older wires. */
+    storage?: number;
+    timestamp: string;
+    timestampServer: number;
+    /** Broker open-time, unix-**millisecond** integer. */
+    timestampOpen: number;
+    timestampOpenServer: number;
+    durationOfPosition: number;
+    comment: string;
+}
+/** Live order event (Appendix A.2, topic `mt5:events:<server>:order`). */
+export interface IOrderEvent {
+    event: typeof WS_EVENT_NAME.ORDER;
+    eventId: string;
+    server: string;
+    login: number;
+    orderId: number;
+    symbol: string;
+    volume: number;
+    price: number;
+    priceSl: number;
+    priceTp: number;
+    /** Raw MT5 integer code; `orderTypeStr` is the decoded form. */
+    orderType: number;
+    orderTypeStr: string;
+    /** Raw MT5 integer code; `stateStr` is the decoded form. */
+    state: number;
+    stateStr: string;
+    duration: string;
+    timestampSetup: number;
+    timestamp: string;
+    comment: string;
+}
+/** Live deal event (Appendix A.4, topic `mt5:events:<server>:deal`). */
+export interface IDealEvent {
+    event: typeof WS_EVENT_NAME.DEAL;
+    eventId: string;
+    server: string;
+    login: number;
+    dealId: number;
+    orderId: number;
+    positionId: number;
+    action: MT5TradeSide;
+    entry: MT5DealEntry;
+    symbol: string;
+    volume: number;
+    price: number;
+    profit: number;
+    commission: number;
+    fee: number;
+    storage: number;
+    swap: number;
+    comment: string;
+    reason: number;
+    externalId: string;
+    timestamp: string;
+    timestampServer: number;
+    group: string;
+    currency: string;
+}
+/**
+ * Tick event (Appendix A.1, topic `mt5:events:<server>:tick` **or**
+ * `symbol:<server>:<SYMBOL>`). Note: there is **no** `event` discriminator in
+ * the payload — dispatch on `topic` (or on `data.event: "symbol_tick"`).
+ */
+export interface ITickEvent {
+    eventId: string;
+    server: string;
+    symbol: string;
+    bid: number;
+    ask: number;
+    last: number;
+    volume: number;
+    timestamp: string;
+    flags: number;
+}
+/**
+ * Single depth-of-market (DOM) ladder level. The backend emits one DOM
+ * snapshot per symbol; consumers aggregate the levels into a bid/ask ladder.
+ */
+export interface IDomEntry {
+    price: number;
+    quantity: number;
+}
+/**
+ * Depth-of-market snapshot event. Delivered on a per-symbol DOM topic; there is
+ * no `event` discriminator — dispatch on `topic` + the `symbol` field. The
+ * ladder (`dom[]`) is the authoritative bid/ask depth at the snapshot time.
+ */
+export interface IDomEvent {
+    symbol: string;
+    dom: IDomEntry[];
+}
+/**
+ * Time & sales (the tape) event. Each frame is one executed print for a symbol;
+ * dispatched on `topic` (no `event` discriminator). `side` uses the decoded
+ * `'BUY' | 'SELL'` form.
+ */
+export interface ITimeNSaleEvent {
+    symbol: string;
+    price: number;
+    side: MT5TradeSide;
+    quantity: number;
+    timestamp: string;
+}
+//# sourceMappingURL=ws.events.d.ts.map

package/dist/core/ws/ws.events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws.events.d.ts","sourceRoot":"","sources":["../../../src/core/ws/ws.events.ts"],"names":[],"mappings":"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"}