Expand types, add type guards, flesh out futures position example

src/futures-client.ts

@@ -17,6 +17,8 @@ import {
   NewFuturesPlanStopOrder,
   FuturesAccount,
   FuturesSymbolRule,
+  FuturesMarginMode,
+  FuturesPosition,
 } from './types';
 import { REST_CLIENT_TYPE_ENUM } from './util';
 import BaseRestClient from './util/BaseRestClient';
@@ -198,7 +200,7 @@ export class FuturesClient extends BaseRestClient {
   setMarginMode(
     symbol: string,
     marginCoin: string,
-    marginMode: 'fixed' | 'crossed'
+    marginMode: FuturesMarginMode
   ): Promise<APIResponse<any>> {
     return this.postPrivate('/api/mix/v1/account/setMarginMode', {
       symbol,
@@ -208,7 +210,10 @@ export class FuturesClient extends BaseRestClient {
   }
 
   /** Get Symbol Position */
-  getPosition(symbol: string, marginCoin?: string): Promise<APIResponse<any>> {
+  getPosition(
+    symbol: string,
+    marginCoin?: string
+  ): Promise<APIResponse<FuturesPosition[]>> {
     return this.getPrivate('/api/mix/v1/position/singlePosition', {
       symbol,
       marginCoin,
@@ -219,7 +224,7 @@ export class FuturesClient extends BaseRestClient {
   getPositions(
     productType: FuturesProductType,
     marginCoin?: string
-  ): Promise<APIResponse<any>> {
+  ): Promise<APIResponse<FuturesPosition[]>> {
     return this.getPrivate('/api/mix/v1/position/allPosition', {
       productType,
       marginCoin,

src/types/request/futures.ts

@@ -8,6 +8,12 @@ export type FuturesProductType =
   | 'sdmcbl'
   | 'scmcbl';
 
+export type FuturesHoldSide = 'long' | 'short';
+
+export type FuturesMarginMode = 'fixed' | 'crossed';
+
+export type FuturesHoldMode = 'double_hold' | 'single_hold';
+
 export interface FuturesAccountBillRequest {
   symbol: string;
   marginCoin: string;
@@ -95,7 +101,6 @@ export interface ModifyFuturesPlanOrderTPSL {
 }
 
 export type FuturesPlanType = 'profit_plan' | 'loss_plan';
-export type FuturesHoldSide = 'long' | 'short';
 
 export interface NewFuturesPlanStopOrder {
   symbol: string;

src/types/response/futures.ts

@@ -1,3 +1,9 @@
+import {
+  FuturesHoldMode,
+  FuturesHoldSide,
+  FuturesMarginMode,
+} from '../request';
+
 export interface FuturesAccount {
   marginCoin: string;
   locked: number;
@@ -33,3 +39,24 @@ export interface FuturesSymbolRule {
   takerFeeRate: string;
   volumePlace: string;
 }
+
+export interface FuturesPosition {
+  marginCoin: string;
+  symbol: string;
+  holdSide: FuturesHoldSide;
+  openDelegateCount: string;
+  margin: string;
+  available: string;
+  locked: string;
+  total: string;
+  leverage: number;
+  achievedProfits: string;
+  averageOpenPrice: string;
+  marginMode: FuturesMarginMode;
+  holdMode: FuturesHoldMode;
+  unrealizedPL: string;
+  liquidationPrice: string;
+  keepMarginRate: string;
+  marketPrice: string;
+  cTime: string;
+}

src/types/websockets/client.ts

@@ -1,4 +1,4 @@
-import { WS_KEY_MAP } from '../util';
+import { WS_KEY_MAP } from '../../util';
 
 export type WsPublicSpotTopic =
   | 'ticker'

src/types/websockets/events.ts

@@ -0,0 +1,82 @@
+export interface WsBaseEvent<TAction = 'snapshot' | string, TData = unknown> {
+  action: TAction;
+  arg: unknown;
+  data: TData[];
+}
+
+export interface WsSnapshotChannelEvent extends WsBaseEvent<'snapshot'> {
+  arg: {
+    instType: string;
+    channel: string;
+    instId: string;
+  };
+}
+
+export interface WsSnapshotAccountEvent extends WsBaseEvent<'snapshot'> {
+  arg: {
+    instType: string;
+    channel: 'account';
+    instId: string;
+  };
+}
+
+export interface WsSnapshotPositionsEvent extends WsBaseEvent<'snapshot'> {
+  arg: {
+    instType: string;
+    channel: 'positions';
+    instId: string;
+  };
+}
+
+export interface WsAccountSnapshotUMCBL extends WsBaseEvent<'snapshot'> {
+  arg: {
+    instType: 'umcbl';
+    channel: 'account';
+    instId: string;
+  };
+  data: WsAccountSnapshotDataUMCBL[];
+}
+
+export interface WsAccountSnapshotDataUMCBL {
+  marginCoin: string;
+  locked: string;
+  available: string;
+  maxOpenPosAvailable: string;
+  maxTransferOut: string;
+  equity: string;
+  usdtEquity: string;
+}
+
+export interface WSPositionSnapshotUMCBL extends WsBaseEvent<'snapshot'> {
+  arg: {
+    instType: 'umcbl';
+    channel: 'positions';
+    instId: string;
+  };
+  data: WsPositionSnapshotDataUMCBL[];
+}
+
+export interface WsPositionSnapshotDataUMCBL {
+  posId: string;
+  instId: string;
+  instName: string;
+  marginCoin: string;
+  margin: string;
+  marginMode: string;
+  holdSide: string;
+  holdMode: string;
+  total: string;
+  available: string;
+  locked: string;
+  averageOpenPrice: string;
+  leverage: number;
+  achievedProfits: string;
+  upl: string;
+  uplRate: string;
+  liqPx: string;
+  keepMarginRate: string;
+  marginRate: string;
+  cTime: string;
+  uTime: string;
+  markPrice: string;
+}

src/types/websockets/index.ts

@@ -0,0 +1,2 @@
+export * from './client';
+export * from './events';

src/util/index.ts

@@ -2,4 +2,5 @@ export * from './BaseRestClient';
 export * from './requestUtils';
 export * from './WsStore';
 export * from './logger';
+export * from './type-guards';
 export * from './websocket-util';

src/util/type-guards.ts

@@ -0,0 +1,73 @@
+import {
+  WsAccountSnapshotUMCBL,
+  WsBaseEvent,
+  WSPositionSnapshotUMCBL,
+  WsSnapshotAccountEvent,
+  WsSnapshotChannelEvent,
+  WsSnapshotPositionsEvent,
+} from '../types';
+
+/** TypeGuard: event has a string "action" property */
+function isWsEvent(event: unknown): event is WsBaseEvent {
+  return (
+    typeof event === 'object' &&
+    event &&
+    typeof event['action'] === 'string' &&
+    event['data']
+  );
+}
+
+/** TypeGuard: event has "action === snapshot" */
+function isWsSnapshotEvent(event: unknown): event is WsBaseEvent<'snapshot'> {
+  return isWsEvent(event) && event.action === 'snapshot';
+}
+
+/** TypeGuard: event has a string channel name */
+function isWsChannelEvent(event: WsBaseEvent): event is WsSnapshotChannelEvent {
+  if (
+    typeof event['arg'] === 'object' &&
+    event.arg &&
+    typeof event?.arg['channel'] === 'string'
+  ) {
+    return true;
+  }
+  return false;
+}
+
+/** TypeGuard: event is an account update (balance) */
+export function isWsAccountSnapshotEvent(
+  event: unknown
+): event is WsSnapshotAccountEvent {
+  return (
+    isWsSnapshotEvent(event) &&
+    isWsChannelEvent(event) &&
+    event.arg.channel === 'account' &&
+    Array.isArray(event.data)
+  );
+}
+
+/** TypeGuard: event is a positions update */
+export function isWsPositionsSnapshotEvent(
+  event: unknown
+): event is WsSnapshotPositionsEvent {
+  return (
+    isWsSnapshotEvent(event) &&
+    isWsChannelEvent(event) &&
+    event.arg.channel === 'positions' &&
+    Array.isArray(event.data)
+  );
+}
+
+/** TypeGuard: event is a UMCBL account update (balance) */
+export function isWsFuturesAccountSnapshotEvent(
+  event: unknown
+): event is WsAccountSnapshotUMCBL {
+  return isWsAccountSnapshotEvent(event) && event.arg.instType === 'umcbl';
+}
+
+/** TypeGuard: event is a UMCBL positions update */
+export function isWsFuturesPositionsSnapshotEvent(
+  event: unknown
+): event is WSPositionSnapshotUMCBL {
+  return isWsPositionsSnapshotEvent(event) && event.arg.instType === 'umcbl';
+}