laplace-api 3.0.1 → 3.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "laplace-api",
-  "version": "3.0.1",
+  "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/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),
+        },
+      });
+    }
+  });
+});