laplace-api 3.0.0 → 3.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "laplace-api",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Client library for Laplace API for the US stock market and BIST (Istanbul stock market) fundamental financial data.",
   "main": "index.js",
   "scripts": {

package/src/client/broker.ts

@@ -0,0 +1,197 @@
+import { Client } from "./client";
+import { Region } from "./collections";
+import { AssetClass, AssetType } from "./stocks";
+
+export enum BrokerSort {
+  NetBuy = "netBuy",
+  NetSell = "netSell",
+  Volume = "volume",
+}
+
+export interface Broker {
+  id: number;
+  symbol: string;
+  name: string;
+  longName: string;
+  logo: string;
+}
+
+export interface BrokerStock {
+  symbol: string;
+  name: string;
+  id: string;
+  assetType: AssetType;
+  assetClass: AssetClass;
+  region: Region;
+}
+
+export interface BaseBrokerStats {
+  totalBuyAmount: number;
+  totalSellAmount: number;
+  netAmount: number;
+  totalBuyVolume: number;
+  totalSellVolume: number;
+  totalVolume: number;
+  totalAmount: number;
+}
+
+export interface BrokerStats extends BaseBrokerStats {
+  broker: Broker;
+}
+
+export interface MarketBrokersResponse {
+  recordCount: number;
+  totalStats: BaseBrokerStats;
+  items: BrokerStats[];
+}
+
+export interface TopBrokersResponse {
+  topStats: BaseBrokerStats;
+  restStats: BaseBrokerStats;
+  topItems: BrokerStats[];
+}
+
+export interface StockBrokerStats extends BaseBrokerStats {
+  averageCost: number;
+  broker: Broker;
+}
+
+export interface StockOverallStats extends BaseBrokerStats {
+  averageCost: number;
+}
+
+export interface StockBrokersResponse {
+  recordCount: number;
+  totalStats: StockOverallStats;
+  items: StockBrokerStats[];
+}
+
+export interface TopStockBrokersResponse {
+  topStats: StockOverallStats;
+  restStats: StockOverallStats;
+  topItems: StockBrokerStats[];
+}
+
+export interface BrokerStockStats extends BaseBrokerStats {
+  stock: BrokerStock;
+}
+
+export interface TopStocksForBrokerResponse {
+  topStats: BaseBrokerStats;
+  restStats: BaseBrokerStats;
+  topItems: BrokerStockStats[];
+}
+
+export class BrokerClient extends Client {
+  private static readonly BASE = "/api/v1/brokers";
+
+  async getMarketBrokers(
+    region: Region,
+    fromDate: string,
+    toDate: string,
+    sortBy: BrokerSort,
+    page: number = 0,
+    size: number = 10
+  ): Promise<MarketBrokersResponse> {
+    return this.sendRequest<MarketBrokersResponse>({
+      method: "GET",
+      url: BrokerClient.BASE + "/market",
+      params: {
+        region,
+        fromDate,
+        toDate,
+        sortBy,
+        page,
+        size,
+      },
+    });
+  }
+
+  async getTopMarketBrokers(
+    region: Region,
+    fromDate: string,
+    toDate: string,
+    sortBy: BrokerSort,
+    top: number = 5
+  ): Promise<TopBrokersResponse> {
+    return this.sendRequest<TopBrokersResponse>({
+      method: "GET",
+      url: BrokerClient.BASE + "/market/top",
+      params: {
+        region,
+        fromDate,
+        toDate,
+        sortBy,
+        top,
+      },
+    });
+  }
+
+  async getStockBrokers(
+    region: Region,
+    fromDate: string,
+    toDate: string,
+    sortBy: BrokerSort,
+    symbol: string,
+    page: number = 0,
+    size: number = 10
+  ): Promise<StockBrokersResponse> {
+    return this.sendRequest<StockBrokersResponse>({
+      method: "GET",
+      url: BrokerClient.BASE + "/stock",
+      params: {
+        region,
+        fromDate,
+        toDate,
+        sortBy,
+        page,
+        size,
+        symbol,
+      },
+    });
+  }
+
+  async getTopStockBrokers(
+    region: Region,
+    fromDate: string,
+    toDate: string,
+    sortBy: BrokerSort,
+    symbol: string,
+    top: number = 5
+  ): Promise<TopStockBrokersResponse> {
+    return this.sendRequest<TopStockBrokersResponse>({
+      method: "GET",
+      url: BrokerClient.BASE + "/stock/top",
+      params: {
+        region,
+        fromDate,
+        toDate,
+        sortBy,
+        top,
+        symbol,
+      },
+    });
+  }
+
+  async getTopStocksForBroker(
+    region: Region,
+    fromDate: string,
+    toDate: string,
+    sortBy: BrokerSort,
+    brokerSymbol: string,
+    top: number = 5
+  ): Promise<TopStocksForBrokerResponse> {
+    return this.sendRequest<TopStocksForBrokerResponse>({
+      method: "GET",
+      url: BrokerClient.BASE + "/top",
+      params: {
+        region,
+        fromDate,
+        toDate,
+        sortBy,
+        top,
+        brokerSymbol,
+      },
+    });
+  }
+}

package/src/client/financial_ratios.ts

@@ -131,7 +131,7 @@ export interface HistoricalFinancialSheets {
 
 export interface HistoricalFinancialSheet {
   period: string;
-  rows: HistoricalFinancialSheetRow[];
+  items: HistoricalFinancialSheetRow[];
 }
 
 export interface HistoricalFinancialSheetRow {

package/src/client/live-price-web-socket.ts

@@ -107,6 +107,9 @@ export class LivePriceWebSocketClient {
   private wsUrl: string | null = null;
   private readonly options: Required<WebSocketOptions>;
   private connectPromise: Promise<void> | null = null;
+  private lastMessageTimestamp: number = 0;
+  private inactivityCheckInterval: NodeJS.Timeout | null = null;
+  private readonly INACTIVITY_TIMEOUT = 15000;
 
   constructor(options: WebSocketOptions = {}) {
     this.options = {
@@ -119,6 +122,32 @@ export class LivePriceWebSocketClient {
     };
   }
 
+  private startInactivityInterval() {
+    this.lastMessageTimestamp = Date.now();
+    if (this.inactivityCheckInterval) {
+      clearInterval(this.inactivityCheckInterval);
+      this.inactivityCheckInterval = null;
+    }
+ 
+    this.inactivityCheckInterval = setInterval(async ()=> {
+      if (Date.now() - this.lastMessageTimestamp >= this.INACTIVITY_TIMEOUT) {
+        this.stopInactivityInterval();
+        try {
+          this.attemptReconnect();
+        } catch(error) {
+          this.log(`Failed to reconnect: ${error}`, "error");
+        }
+      }
+    }, this.INACTIVITY_TIMEOUT)
+  }
+
+  private stopInactivityInterval() {
+    if (this.inactivityCheckInterval) {
+      clearInterval(this.inactivityCheckInterval);
+      this.inactivityCheckInterval = null;
+    }
+  }
+
   private log(message: string, level: "info" | "error" | "warn" = "info") {
     if (!this.options.enableLogging) return;
 
@@ -183,6 +212,7 @@ export class LivePriceWebSocketClient {
       this.ws.onopen = () => {
         this.reconnectAttempts = 0;
         this.log("WebSocket connected");
+        this.startInactivityInterval();
         resolve();
       };
 
@@ -198,6 +228,8 @@ export class LivePriceWebSocketClient {
       this.ws.onclose = () => {
         this.isClosed = true;
         this.log("WebSocket closed");
+
+        this.stopInactivityInterval();
         if (this.closedReason !== WebSocketCloseReason.NORMAL_CLOSURE) {
           try {
             this.attemptReconnect();
@@ -225,6 +257,7 @@ export class LivePriceWebSocketClient {
       };
 
       this.ws.onmessage = (event) => {
+        this.lastMessageTimestamp = Date.now();
         try {
           const rawData = JSON.parse(event.data.toString());
 

package/src/test/broker.test.ts

@@ -0,0 +1,262 @@
+import { Logger } from "winston";
+import { Region } from "../client/collections";
+import { LaplaceConfiguration } from "../utilities/configuration";
+import "./client_test_suite";
+import {
+  BaseBrokerStats,
+  BrokerClient,
+  BrokerSort,
+  BrokerStats,
+  BrokerStockStats,
+  StockBrokerStats,
+  StockOverallStats,
+} from "../client/broker";
+
+describe("BrokerClient", () => {
+  let brokerClient: BrokerClient;
+
+  beforeAll(() => {
+    const config = (global as any).testSuite.config as LaplaceConfiguration;
+
+    const logger: Logger = {
+      info: jest.fn(),
+      error: jest.fn(),
+      warn: jest.fn(),
+      debug: jest.fn(),
+    } as unknown as Logger;
+
+    brokerClient = new BrokerClient(config, logger);
+  });
+
+  const region = Region.Tr;
+  const fromDate = "2025-05-20";
+  const toDate = "2025-05-28";
+
+  test("getMarketBrokers returns valid and fully typed data", async () => {
+    const response = await brokerClient.getMarketBrokers(
+      Region.Tr,
+      "2025-05-27",
+      "2025-05-28",
+      BrokerSort.Volume,
+      0,
+      5
+    );
+
+    expect(response).toBeDefined();
+    expect(typeof response.recordCount).toBe("number");
+
+    const stats = response.totalStats;
+    expect(stats).toMatchObject<BaseBrokerStats>({
+      totalBuyAmount: expect.any(Number),
+      totalSellAmount: expect.any(Number),
+      netAmount: expect.any(Number),
+      totalBuyVolume: expect.any(Number),
+      totalSellVolume: expect.any(Number),
+      totalVolume: expect.any(Number),
+      totalAmount: expect.any(Number),
+    });
+
+    expect(Array.isArray(response.items)).toBe(true);
+    expect(response.items.length).toBeGreaterThan(0);
+
+    for (const item of response.items) {
+      expect(item).toMatchObject<BrokerStats>({
+        totalBuyAmount: expect.any(Number),
+        totalSellAmount: expect.any(Number),
+        netAmount: expect.any(Number),
+        totalBuyVolume: expect.any(Number),
+        totalSellVolume: expect.any(Number),
+        totalVolume: expect.any(Number),
+        totalAmount: expect.any(Number),
+        broker: {
+          id: expect.any(Number),
+          symbol: expect.any(String),
+          name: expect.any(String),
+          longName: expect.any(String),
+          logo: expect.any(String),
+        },
+      });
+    }
+  });
+
+  test("getTopMarketBrokers returns fully typed top and rest stats", async () => {
+    const response = await brokerClient.getTopMarketBrokers(
+      region,
+      fromDate,
+      toDate,
+      BrokerSort.Volume
+    );
+
+    expect(response).toBeDefined();
+
+    const statsList = [response.topStats, response.restStats];
+    for (const stats of statsList) {
+      expect(stats).toMatchObject<BaseBrokerStats>({
+        totalBuyAmount: expect.any(Number),
+        totalSellAmount: expect.any(Number),
+        netAmount: expect.any(Number),
+        totalBuyVolume: expect.any(Number),
+        totalSellVolume: expect.any(Number),
+        totalVolume: expect.any(Number),
+        totalAmount: expect.any(Number),
+      });
+    }
+
+    expect(Array.isArray(response.topItems)).toBe(true);
+    expect(response.topItems.length).toBeGreaterThan(0);
+
+    for (const item of response.topItems) {
+      expect(item).toMatchObject<BrokerStats>({
+        totalBuyAmount: expect.any(Number),
+        totalSellAmount: expect.any(Number),
+        netAmount: expect.any(Number),
+        totalBuyVolume: expect.any(Number),
+        totalSellVolume: expect.any(Number),
+        totalVolume: expect.any(Number),
+        totalAmount: expect.any(Number),
+        broker: {
+          id: expect.any(Number),
+          symbol: expect.any(String),
+          name: expect.any(String),
+          longName: expect.any(String),
+          logo: expect.any(String),
+        },
+      });
+    }
+  });
+
+  test("getStockBrokers returns full broker stats with averageCost", async () => {
+    const response = await brokerClient.getStockBrokers(
+      region,
+      fromDate,
+      toDate,
+      BrokerSort.Volume,
+      "TUPRS",
+      0,
+      5
+    );
+
+    expect(response).toBeDefined();
+    expect(typeof response.recordCount).toBe("number");
+
+    expect(response.totalStats).toMatchObject<StockOverallStats>({
+      totalBuyAmount: expect.any(Number),
+      totalSellAmount: expect.any(Number),
+      netAmount: expect.any(Number),
+      totalBuyVolume: expect.any(Number),
+      totalSellVolume: expect.any(Number),
+      totalVolume: expect.any(Number),
+      totalAmount: expect.any(Number),
+      averageCost: expect.any(Number),
+    });
+
+    for (const item of response.items) {
+      expect(item).toMatchObject<StockBrokerStats>({
+        averageCost: expect.any(Number),
+        totalBuyAmount: expect.any(Number),
+        totalSellAmount: expect.any(Number),
+        netAmount: expect.any(Number),
+        totalBuyVolume: expect.any(Number),
+        totalSellVolume: expect.any(Number),
+        totalVolume: expect.any(Number),
+        totalAmount: expect.any(Number),
+        broker: {
+          id: expect.any(Number),
+          symbol: expect.any(String),
+          name: expect.any(String),
+          longName: expect.any(String),
+          logo: expect.any(String),
+        },
+      });
+    }
+  });
+
+  test("getTopStockBrokers returns fully typed top & rest stats with averageCost", async () => {
+    const response = await brokerClient.getTopStockBrokers(
+      region,
+      fromDate,
+      toDate,
+      BrokerSort.Volume,
+      "TUPRS"
+    );
+
+    expect(response).toBeDefined();
+
+    for (const stats of [response.topStats, response.restStats]) {
+      expect(stats).toMatchObject<StockOverallStats>({
+        totalBuyAmount: expect.any(Number),
+        totalSellAmount: expect.any(Number),
+        netAmount: expect.any(Number),
+        totalBuyVolume: expect.any(Number),
+        totalSellVolume: expect.any(Number),
+        totalVolume: expect.any(Number),
+        totalAmount: expect.any(Number),
+        averageCost: expect.any(Number),
+      });
+    }
+
+    for (const item of response.topItems) {
+      expect(item).toMatchObject<StockBrokerStats>({
+        averageCost: expect.any(Number),
+        totalBuyAmount: expect.any(Number),
+        totalSellAmount: expect.any(Number),
+        netAmount: expect.any(Number),
+        totalBuyVolume: expect.any(Number),
+        totalSellVolume: expect.any(Number),
+        totalVolume: expect.any(Number),
+        totalAmount: expect.any(Number),
+        broker: {
+          id: expect.any(Number),
+          symbol: expect.any(String),
+          name: expect.any(String),
+          longName: expect.any(String),
+          logo: expect.any(String),
+        },
+      });
+    }
+  });
+
+  test("getTopBrokersForBroker returns top brokers without averageCost", async () => {
+    const response = await brokerClient.getTopStocksForBroker(
+      region,
+      fromDate,
+      toDate,
+      BrokerSort.Volume,
+      "BIYKR"
+    );
+
+    expect(response).toBeDefined();
+
+    for (const stats of [response.topStats, response.restStats]) {
+      expect(stats).toMatchObject<BaseBrokerStats>({
+        totalBuyAmount: expect.any(Number),
+        totalSellAmount: expect.any(Number),
+        netAmount: expect.any(Number),
+        totalBuyVolume: expect.any(Number),
+        totalSellVolume: expect.any(Number),
+        totalVolume: expect.any(Number),
+        totalAmount: expect.any(Number),
+      });
+    }
+
+    for (const item of response.topItems) {
+      expect(item).toMatchObject<BrokerStockStats>({
+        totalBuyAmount: expect.any(Number),
+        totalSellAmount: expect.any(Number),
+        netAmount: expect.any(Number),
+        totalBuyVolume: expect.any(Number),
+        totalSellVolume: expect.any(Number),
+        totalVolume: expect.any(Number),
+        totalAmount: expect.any(Number),
+        stock: {
+          id: expect.any(String),
+          symbol: expect.any(String),
+          name: expect.any(String),
+          assetType: expect.any(String),
+          assetClass: expect.any(String),
+          region: expect.any(String),
+        },
+      });
+    }
+  });
+});

package/src/test/financial_ratios.test.ts

@@ -7,6 +7,7 @@ import {
   FinancialSheetType,
   FinancialSheetPeriod,
   Currency,
+  HistoricalFinancialSheetRow,
 } from "../client/financial_ratios";
 import { Region, Locale } from "../client/collections";
 import "./client_test_suite";
@@ -74,6 +75,35 @@ describe('FinancialRatios', () => {
       Currency.TRY,
       Region.Tr
     );
+
+    expect(resp).toBeDefined();
+    expect(resp).not.toBeNull();
     expect(resp).not.toBeEmpty();
+
+    expect(resp.sheets).toBeDefined();
+    expect(Array.isArray(resp.sheets)).toBe(true);
+    expect(resp.sheets.length).toBeGreaterThan(0);
+
+    const firstSheet = resp.sheets[0];
+    expect(firstSheet).toBeDefined();
+
+    expect(firstSheet.period).toBeDefined();
+    expect(typeof firstSheet.period).toBe("string")
+
+    expect(firstSheet.items).toBeDefined();
+    expect(Array.isArray(firstSheet.items)).toBe(true);
+    expect(firstSheet.items.length).toBeGreaterThan(0);
+
+    const firstRow = firstSheet.items[0];
+    expect(firstRow).toBeDefined();
+
+    expect(firstRow).toMatchObject<HistoricalFinancialSheetRow>({
+      description: expect.any(String),
+      value: expect.any(Number),
+      lineCodeId: expect.any(Number),
+      indentLevel: expect.any(Number),
+      firstAncestorLineCodeId: expect.any(Number),
+      sectionLineCodeId: expect.any(Number),
+    });
   });
-});
+});

package/src/utilities/test.env

@@ -1,2 +1,2 @@
-BASE_URL=
-API_KEY=
+BASE_URL=https://api.finfree.app
+API_KEY=api-6fa6cefb-16df-4a19-8351-54f83c6bbe2f