@himalaya-quant/ctrader-x 0.0.7

package/src/classes/managers/symbols/symbols.manager.test.ts

@@ -0,0 +1,455 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { ProtoOASymbolsListReq } from '../../../models/proto/messages/symbols/ProtoOASymbolsListReq';
+import { ProtoOASymbolsListRes } from '../../../models/proto/messages/symbols/ProtoOASymbolsListRes';
+import { ProtoOASymbolByIdReq } from '../../../models/proto/messages/symbols/ProtoOASymbolByIdReq';
+import { ProtoOASymbolByIdRes } from '../../../models/proto/messages/symbols/ProtoOASymbolByIdRes';
+import { ProtoOAGetTrendbarsReq } from '../../../models/proto/messages/symbols/ProtoOAGetTrendbarsReq';
+import { ProtoOAGetTrendbarsRes } from '../../../models/proto/messages/symbols/ProtoOAGetTrendbarsRes';
+import { GetSymbolsListError } from './errors/get-symbols-list.error';
+import { GetSymbolsDetailsError } from './errors/get-symbols-details.error';
+import { GetTrendBarsError } from './errors/get-trend-bars.error';
+import { SymbolsManager } from './symbols.manager';
+import { OHLCVPositions } from '../../../models/common/ohlcv';
+
+describe('SymbolsManager - Unit Tests', () => {
+    let symbolsManager: SymbolsManager;
+    let mockConnection: any;
+    let mockLogger: any;
+    let mockCredentials: any;
+
+    beforeEach(() => {
+        mockConnection = {
+            sendCommand: vi.fn(),
+            on: vi.fn(),
+        };
+
+        mockLogger = {
+            debug: vi.fn(),
+            error: vi.fn(),
+        };
+
+        mockCredentials = {
+            clientId: 'test-client-id',
+            clientSecret: 'test-client-secret',
+            accessToken: 'test-access-token',
+            ctidTraderAccountId: 12345,
+        };
+
+        symbolsManager = new SymbolsManager(
+            mockCredentials,
+            mockConnection,
+            mockLogger,
+        );
+    });
+
+    describe('getSymbolsList', () => {
+        it('should return full symbols list successfully', async () => {
+            const mockSymbolsListResponse: ProtoOASymbolsListRes = {
+                ctidTraderAccountId: 12345,
+                symbol: [
+                    {
+                        symbolId: 1,
+                        symbolName: 'EURUSD',
+                        enabled: true,
+                        baseAssetId: 10,
+                        quoteAssetId: 11,
+                    },
+                    {
+                        symbolId: 2,
+                        symbolName: 'GBPUSD',
+                        enabled: true,
+                        baseAssetId: 12,
+                        quoteAssetId: 11,
+                    },
+                ],
+                archivedSymbol: [],
+            };
+
+            const mockSymbolDetailsResponse: ProtoOASymbolByIdRes = {
+                ctidTraderAccountId: 12345,
+                archivedSymbol: null!,
+                symbol: [
+                    {
+                        symbolId: 1,
+                        digits: 5,
+                        pipPosition: 4,
+                        enableShortSelling: true,
+                        guaranteedStopLoss: false,
+                        swapLong: -1.5,
+                        swapShort: 0.5,
+                        maxVolume: 10000000,
+                        minVolume: 1000,
+                        stepVolume: 1000,
+                        description: 'Euro vs US Dollar',
+                    },
+                    {
+                        symbolId: 2,
+                        digits: 5,
+                        pipPosition: 4,
+                        enableShortSelling: true,
+                        guaranteedStopLoss: false,
+                        swapLong: -2.0,
+                        swapShort: 1.0,
+                        maxVolume: 10000000,
+                        minVolume: 1000,
+                        stepVolume: 1000,
+                        description: 'British Pound vs US Dollar',
+                    },
+                ],
+            };
+
+            mockConnection.sendCommand
+                .mockResolvedValueOnce(mockSymbolsListResponse)
+                .mockResolvedValueOnce(mockSymbolDetailsResponse);
+
+            const result = await symbolsManager.getSymbolsList();
+
+            // Il risultato deve essere il merge tra ProtoOASymbol e ProtoOALightSymbol
+            const expected = [
+                {
+                    symbolId: 1,
+                    digits: 5,
+                    pipPosition: 4,
+                    enableShortSelling: true,
+                    guaranteedStopLoss: false,
+                    swapLong: -1.5,
+                    swapShort: 0.5,
+                    maxVolume: 10000000,
+                    minVolume: 1000,
+                    stepVolume: 1000,
+                    description: 'Euro vs US Dollar',
+                    symbolName: 'EURUSD',
+                    enabled: true,
+                    baseAssetId: 10,
+                    quoteAssetId: 11,
+                },
+                {
+                    symbolId: 2,
+                    digits: 5,
+                    pipPosition: 4,
+                    enableShortSelling: true,
+                    guaranteedStopLoss: false,
+                    swapLong: -2.0,
+                    swapShort: 1.0,
+                    maxVolume: 10000000,
+                    minVolume: 1000,
+                    stepVolume: 1000,
+                    description: 'British Pound vs US Dollar',
+                    symbolName: 'GBPUSD',
+                    enabled: true,
+                    baseAssetId: 12,
+                    quoteAssetId: 11,
+                },
+            ];
+
+            expect(result).toEqual(expected);
+            expect(mockConnection.sendCommand).toHaveBeenCalledTimes(2);
+            expect(mockConnection.sendCommand).toHaveBeenNthCalledWith(
+                1,
+                ProtoOASymbolsListReq.name,
+                {
+                    includeArchivedSymbols: undefined,
+                    ctidTraderAccountId: 12345,
+                },
+            );
+            expect(mockConnection.sendCommand).toHaveBeenNthCalledWith(
+                2,
+                ProtoOASymbolByIdReq.name,
+                {
+                    symbolId: [1, 2],
+                    ctidTraderAccountId: 12345,
+                },
+            );
+        });
+
+        it('should pass includeArchivedSymbols option correctly', async () => {
+            const mockSymbolsListResponse: ProtoOASymbolsListRes = {
+                ctidTraderAccountId: 12345,
+                symbol: [],
+                archivedSymbol: [
+                    {
+                        symbolId: 99,
+                        symbolName: 'ARCHIVED',
+                        enabled: false,
+                        baseAssetId: 1,
+                        quoteAssetId: 2,
+                    },
+                ],
+            };
+
+            const mockSymbolDetailsResponse: ProtoOASymbolByIdRes = {
+                ctidTraderAccountId: 12345,
+                archivedSymbol: null!,
+                symbol: [],
+            };
+
+            mockConnection.sendCommand
+                .mockResolvedValueOnce(mockSymbolsListResponse)
+                .mockResolvedValueOnce(mockSymbolDetailsResponse);
+
+            await symbolsManager.getSymbolsList({
+                includeArchivedSymbols: true,
+            });
+
+            expect(mockConnection.sendCommand).toHaveBeenNthCalledWith(
+                1,
+                ProtoOASymbolsListReq.name,
+                {
+                    includeArchivedSymbols: true,
+                    ctidTraderAccountId: 12345,
+                },
+            );
+        });
+
+        it('should throw GetSymbolsListError on symbols list failure', async () => {
+            mockConnection.sendCommand.mockRejectedValue(
+                new Error('Connection failed'),
+            );
+
+            await expect(symbolsManager.getSymbolsList()).rejects.toThrow(
+                GetSymbolsListError,
+            );
+
+            expect(mockLogger.error).toHaveBeenCalled();
+        });
+
+        it('should throw GetSymbolsDetailsError on symbols details failure', async () => {
+            const mockSymbolsListResponse: ProtoOASymbolsListRes = {
+                ctidTraderAccountId: 12345,
+                symbol: [
+                    {
+                        symbolId: 1,
+                        symbolName: 'EURUSD',
+                        enabled: true,
+                        baseAssetId: 10,
+                        quoteAssetId: 11,
+                    },
+                ],
+                archivedSymbol: [],
+            };
+
+            mockConnection.sendCommand
+                .mockResolvedValueOnce(mockSymbolsListResponse)
+                .mockRejectedValueOnce(new Error('Details fetch failed'));
+
+            await expect(symbolsManager.getSymbolsList()).rejects.toThrow(
+                GetSymbolsDetailsError,
+            );
+
+            expect(mockLogger.error).toHaveBeenCalled();
+        });
+    });
+
+    describe('getSymbolsDetails', () => {
+        it('should return symbols details successfully', async () => {
+            const mockResponse: ProtoOASymbolByIdRes = {
+                ctidTraderAccountId: 12345,
+                archivedSymbol: null!,
+                symbol: [
+                    {
+                        symbolId: 1,
+                        digits: 5,
+                        pipPosition: 4,
+                        enableShortSelling: true,
+                        guaranteedStopLoss: false,
+                        swapLong: -1.5,
+                        swapShort: 0.5,
+                        maxVolume: 10000000,
+                        minVolume: 1000,
+                        stepVolume: 1000,
+                        description: 'Euro vs US Dollar',
+                    },
+                ],
+            };
+
+            mockConnection.sendCommand.mockResolvedValue(mockResponse);
+
+            const result = await symbolsManager.getSymbolsDetails([1]);
+
+            expect(result).toEqual(mockResponse);
+            expect(mockConnection.sendCommand).toHaveBeenCalledWith(
+                ProtoOASymbolByIdReq.name,
+                {
+                    symbolId: [1],
+                    ctidTraderAccountId: 12345,
+                },
+            );
+        });
+
+        it('should handle multiple symbol IDs', async () => {
+            const mockResponse: ProtoOASymbolByIdRes = {
+                ctidTraderAccountId: 12345,
+                archivedSymbol: null!,
+                symbol: [
+                    {
+                        symbolId: 1,
+                        digits: 5,
+                        pipPosition: 4,
+                    },
+                    {
+                        symbolId: 2,
+                        digits: 5,
+                        pipPosition: 4,
+                    },
+                    {
+                        symbolId: 3,
+                        digits: 3,
+                        pipPosition: 2,
+                    },
+                ],
+            };
+
+            mockConnection.sendCommand.mockResolvedValue(mockResponse);
+
+            const result = await symbolsManager.getSymbolsDetails([1, 2, 3]);
+
+            expect(result).toEqual(mockResponse);
+            expect(mockConnection.sendCommand).toHaveBeenCalledWith(
+                ProtoOASymbolByIdReq.name,
+                {
+                    symbolId: [1, 2, 3],
+                    ctidTraderAccountId: 12345,
+                },
+            );
+        });
+
+        it('should throw GetSymbolsDetailsError on failure', async () => {
+            mockConnection.sendCommand.mockRejectedValue(
+                new Error('Connection failed'),
+            );
+
+            await expect(
+                symbolsManager.getSymbolsDetails([1, 2]),
+            ).rejects.toThrow(GetSymbolsDetailsError);
+
+            expect(mockLogger.error).toHaveBeenCalled();
+        });
+    });
+
+    describe('getTrendBars', () => {
+        it('should return trend bars with converted timestamps', async () => {
+            const mockResponse: ProtoOAGetTrendbarsRes = {
+                ctidTraderAccountId: 12345,
+                period: null!,
+                trendbar: [
+                    {
+                        utcTimestampInMinutes: 29350000,
+                        deltaOpen: 108500,
+                        deltaHigh: 108600,
+                        low: 108400,
+                        deltaClose: 108550,
+                        volume: 1000000,
+                    },
+                ],
+            };
+
+            mockConnection.sendCommand.mockResolvedValue(mockResponse);
+            const _getSymbolsDetails =
+                symbolsManager.getSymbolsDetails.bind(symbolsManager);
+            symbolsManager.getSymbolsDetails = vi.fn().mockResolvedValue({
+                symbol: [
+                    {
+                        digits: 3,
+                    },
+                ],
+            });
+
+            const opts = {
+                symbolId: 1,
+                period: 'M1' as any,
+                fromTimestamp: 1640000000000,
+                toTimestamp: 1640086400000,
+            };
+
+            const result = await symbolsManager.getTrendBars(opts);
+            symbolsManager.getSymbolsDetails = _getSymbolsDetails;
+
+            // Verify timestamps are converted (multiplied by 60000)
+            expect(result[0][OHLCVPositions.TIME]).toBe(29350000 * 60000);
+            expect(mockConnection.sendCommand).toHaveBeenCalledWith(
+                ProtoOAGetTrendbarsReq.name,
+                {
+                    ...opts,
+                    ctidTraderAccountId: 12345,
+                },
+            );
+        });
+
+        it('should convert all timestamps in multiple trend bars', async () => {
+            const mockResponse: ProtoOAGetTrendbarsRes = {
+                ctidTraderAccountId: 12345,
+                period: null!,
+                trendbar: [
+                    {
+                        utcTimestampInMinutes: 1000,
+                        deltaOpen: 108500,
+                        deltaHigh: 108600,
+                        low: 108400,
+                        deltaClose: 108550,
+                        volume: 1000000,
+                    },
+                    {
+                        utcTimestampInMinutes: 2000,
+                        deltaOpen: 108600,
+                        deltaHigh: 108700,
+                        low: 108500,
+                        deltaClose: 108650,
+                        volume: 1500000,
+                    },
+                    {
+                        utcTimestampInMinutes: 3000,
+                        deltaOpen: 108650,
+                        deltaHigh: 108750,
+                        low: 108600,
+                        deltaClose: 108700,
+                        volume: 2000000,
+                    },
+                ],
+            };
+
+            mockConnection.sendCommand.mockResolvedValue(mockResponse);
+            const _getSymbolsDetails =
+                symbolsManager.getSymbolsDetails.bind(symbolsManager);
+            symbolsManager.getSymbolsDetails = vi.fn().mockResolvedValue({
+                symbol: [
+                    {
+                        digits: 3,
+                    },
+                ],
+            });
+
+            const opts = {
+                symbolId: 1,
+                period: 'M1' as any,
+                fromTimestamp: 1640000000000,
+                toTimestamp: 1640086400000,
+            };
+
+            const result = await symbolsManager.getTrendBars(opts);
+            symbolsManager.getSymbolsDetails = _getSymbolsDetails;
+
+            expect(result[0][OHLCVPositions.TIME]).toBe(1000 * 60000);
+            expect(result[1][OHLCVPositions.TIME]).toBe(2000 * 60000);
+            expect(result[2][OHLCVPositions.TIME]).toBe(3000 * 60000);
+        });
+
+        it('should throw GetTrendBarsError on failure', async () => {
+            mockConnection.sendCommand.mockRejectedValue(
+                new Error('Connection failed'),
+            );
+
+            const opts = {
+                symbolId: 1,
+                period: 'M1' as any,
+                fromTimestamp: 1640000000000,
+                toTimestamp: 1640086400000,
+            };
+
+            await expect(symbolsManager.getTrendBars(opts)).rejects.toThrow(
+                GetTrendBarsError,
+            );
+
+            expect(mockLogger.error).toHaveBeenCalled();
+        });
+    });
+});

package/src/classes/managers/symbols/symbols.manager.ts

@@ -0,0 +1,134 @@
+import { CTraderConnection } from '@reiryoku/ctrader-layer';
+import { ILogger } from '../../logger';
+import { BaseManager } from '../models/base.manager';
+import { ProtoOASymbolsListReq } from '../../../models/proto/messages/symbols/ProtoOASymbolsListReq';
+import { ICredentials } from '../models/credentials.model';
+import { ProtoOASymbolsListRes } from '../../../models/proto/messages/symbols/ProtoOASymbolsListRes';
+import { GetSymbolsListError } from './errors/get-symbols-list.error';
+import { ProtoOAGetTrendbarsRes } from '../../../models/proto/messages/symbols/ProtoOAGetTrendbarsRes';
+import { ProtoOAGetTrendbarsReq } from '../../../models/proto/messages/symbols/ProtoOAGetTrendbarsReq';
+import { GetTrendBarsError } from './errors/get-trend-bars.error';
+import { ProtoOASymbolByIdRes } from '../../../models/proto/messages/symbols/ProtoOASymbolByIdRes';
+import { ProtoOASymbolByIdReq } from '../../../models/proto/messages/symbols/ProtoOASymbolByIdReq';
+import { GetSymbolsDetailsError } from './errors/get-symbols-details.error';
+import { ProtoOASymbol } from '../../../models/proto/models/ProtoOASymbol';
+import { ProtoOALightSymbol } from '../../../models/proto/models/ProtoOALightSymbol';
+import { TrendBarUtils } from '../../../utils/trendbar.utils';
+import { OHLCV } from '../../../models/common/ohlcv';
+import { ProtoOATrendbarPeriod } from '../../../models/proto/models/ProtoOATrendbarPeriod';
+
+export interface IGetSymbolsListOptions {
+    includeArchivedSymbols?: boolean;
+}
+
+export type GetSymbolsListResult = (ProtoOASymbol & ProtoOALightSymbol)[];
+
+export interface SubscribeLiveTrendBarsEvent {
+    symbolId: number;
+    ohlcv: OHLCV;
+    lastBarTime: number;
+    period: ProtoOATrendbarPeriod;
+}
+
+export class SymbolsManager extends BaseManager {
+    constructor(
+        protected readonly credentials: ICredentials,
+        protected readonly connection: CTraderConnection,
+        protected readonly logger: ILogger,
+    ) {
+        super();
+    }
+
+    async getSymbolsList(
+        opts?: IGetSymbolsListOptions,
+    ): Promise<GetSymbolsListResult> {
+        this.logCallAttempt(this.getSymbolsList);
+
+        const payload: ProtoOASymbolsListReq = {
+            includeArchivedSymbols: opts?.includeArchivedSymbols,
+            ctidTraderAccountId: this.credentials.ctidTraderAccountId,
+        };
+
+        let result: ProtoOASymbolsListRes;
+        try {
+            result = (await this.connection.sendCommand(
+                ProtoOASymbolsListReq.name,
+                payload,
+            )) as ProtoOASymbolsListRes;
+        } catch (e) {
+            throw this.handleCTraderCallError(
+                e,
+                this.getSymbolsList,
+                new GetSymbolsListError(e),
+            );
+        }
+
+        this.logCallAttemptSuccess(this.getSymbolsList);
+
+        const fullSymbols = await this.getSymbolsDetails(
+            result.symbol.map(({ symbolId }) => +symbolId),
+        );
+
+        return fullSymbols.symbol.map((symbol) => ({
+            ...symbol,
+            ...result.symbol.find((s) => s.symbolId === symbol.symbolId),
+        }));
+    }
+
+    async getSymbolsDetails(
+        symbolsIds: number[],
+    ): Promise<ProtoOASymbolByIdRes> {
+        this.logCallAttempt(this.getSymbolsDetails);
+
+        const payload: ProtoOASymbolByIdReq = {
+            symbolId: symbolsIds,
+            ctidTraderAccountId: this.credentials.ctidTraderAccountId,
+        };
+
+        let result: ProtoOASymbolByIdRes;
+        try {
+            result = (await this.connection.sendCommand(
+                ProtoOASymbolByIdReq.name,
+                payload,
+            )) as ProtoOASymbolByIdRes;
+        } catch (e) {
+            throw this.handleCTraderCallError(
+                e,
+                this.getSymbolsDetails,
+                new GetSymbolsDetailsError(e),
+            );
+        }
+
+        this.logCallAttemptSuccess(this.getSymbolsDetails);
+        return result;
+    }
+
+    async getTrendBars(
+        opts: Omit<ProtoOAGetTrendbarsReq, 'ctidTraderAccountId'>,
+    ): Promise<OHLCV[]> {
+        this.logCallAttempt(this.getTrendBars);
+        let result: ProtoOAGetTrendbarsRes;
+        try {
+            const payload: ProtoOAGetTrendbarsReq = {
+                ...opts,
+                ctidTraderAccountId: this.credentials.ctidTraderAccountId,
+            };
+            result = (await this.connection.sendCommand(
+                ProtoOAGetTrendbarsReq.name,
+                payload,
+            )) as ProtoOAGetTrendbarsRes;
+        } catch (e) {
+            throw this.handleCTraderCallError(
+                e,
+                this.getTrendBars,
+                new GetTrendBarsError(e),
+            );
+        }
+
+        this.logCallAttemptSuccess(this.getTrendBars);
+
+        const symbolInfo = await this.getSymbolsDetails([opts.symbolId]);
+        const precision = +symbolInfo.symbol[0].digits;
+        return TrendBarUtils.mapTrendbarsToOHLCV(result.trendbar, precision);
+    }
+}

package/src/classes/models/client-configuration.model.ts

@@ -0,0 +1,39 @@
+import { ILogger } from '../logger';
+
+export interface IConfiguration {
+    /**
+     * Will connect to the live API instead of the demo API
+     * By default the demo API is used.
+     */
+    live?: boolean;
+
+    /**
+     * The Spotware client id.
+     * If not specified will attempt loading from env
+     */
+    clientId?: string;
+
+    /**
+     * The Spotware client secret.
+     * If not specified will attempt loading from env
+     */
+    clientSecret?: string;
+
+    /**
+     * The Spotware access token.
+     * If not specified will attempt loading from env
+     */
+    accessToken?: string;
+
+    /**
+     * The Spotware ctid trader account id.
+     * In the sandbox environment can be found under the Trading accounts tab
+     * If not specified will attempt loading from env
+     */
+    ctidTraderAccountId?: number;
+
+    /**
+     * Custom logger implementation
+     */
+    logger?: ILogger;
+}

package/src/classes/models/ctrader-x-error.model.ts

@@ -0,0 +1,16 @@
+import { ProtoOAErrorRes } from '../../models/proto/models/ProtoOAErrorRes';
+
+export class cTraderXError extends Error {
+    static getMessageError(error: unknown): string {
+        if (this.isProtoOAErrorRes(error))
+            return `${error.errorCode} --> ${error.description} (RetryAfter: ${error.retryAfter} MaintenanceEnd: ${error.maintenanceEndTimestamp})`;
+        if (error instanceof Error) return error.message || error.name;
+        if (typeof error === 'string') return error;
+        return JSON.stringify(error);
+    }
+
+    static isProtoOAErrorRes(error: any): error is ProtoOAErrorRes {
+        if (error.payloadType && error.errorCode) return true;
+        return false;
+    }
+}

package/src/config/config.ts

@@ -0,0 +1,48 @@
+import * as dotenv from 'dotenv';
+import * as process from 'node:process';
+
+dotenv.config({ override: true });
+
+export class Config {
+    static get SPOTWARE_CTID_TRADER_ACCOUNT_ID() {
+        this.ensureConfigExistenceOrThrow(
+            'CTRADERX_SPOTWARE_CTID_TRADER_ACCOUNT_ID',
+        );
+        const value = this.getConfig(
+            'CTRADERX_SPOTWARE_CTID_TRADER_ACCOUNT_ID',
+        );
+        if (!!value && !isNaN(+value)) return +value;
+        throw new Error(
+            `Invalid CTRADERX_SPOTWARE_CTID_TRADER_ACCOUNT_ID. Should be a number`,
+        );
+    }
+
+    static get SPOTWARE_ACCESS_TOKEN() {
+        this.ensureConfigExistenceOrThrow('CTRADERX_SPOTWARE_ACCESS_TOKEN');
+        return this.getConfig('CTRADERX_SPOTWARE_ACCESS_TOKEN');
+    }
+
+    static get SPOTWARE_CLIENT_SECRET() {
+        this.ensureConfigExistenceOrThrow('CTRADERX_SPOTWARE_CLIENT_SECRET');
+        return this.getConfig('CTRADERX_SPOTWARE_CLIENT_SECRET');
+    }
+
+    static get SPOTWARE_CLIENT_ID() {
+        this.ensureConfigExistenceOrThrow('CTRADERX_SPOTWARE_CLIENT_ID');
+        return this.getConfig('CTRADERX_SPOTWARE_CLIENT_ID');
+    }
+
+    static get DEBUG_LOGS() {
+        this.ensureConfigExistenceOrThrow('CTRADERX_DEBUG_LOGS');
+        return this.getConfig('CTRADERX_DEBUG_LOGS') === 'true';
+    }
+
+    private static ensureConfigExistenceOrThrow(config: string): void {
+        if (!process.env[config])
+            throw new Error(`Missing env config ${config}. Please provide it`);
+    }
+
+    private static getConfig(config: string): string {
+        return process.env[config]!;
+    }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './classes/client';
+export * from './classes/logger';
+
+export * from './utils/trendbar.utils';