laplace-api 1.0.0 → 1.0.1

package/jest.config.js

@@ -2,4 +2,5 @@ module.exports = {
     preset: 'ts-jest',
     testEnvironment: 'node',
     setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
+    rootDir: './src',
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "laplace-api",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Client library for Laplace API for the US stock market and BIST (Istanbul stock market) fundamental financial data.",
   "main": "index.js",
   "scripts": {
@@ -35,14 +35,18 @@
   },
   "homepage": "https://github.com/Laplace-Analytics/laplace-api-js#readme",
   "dependencies": {
+    "@types/uuid": "^10.0.0",
     "axios": "^1.7.7",
     "dotenv": "^16.4.5",
     "envalid": "^8.0.0",
+    "event-source-polyfill": "^1.0.31",
     "mongodb": "^6.8.0",
+    "uuid": "^10.0.0",
     "winston": "^3.14.2"
   },
   "devDependencies": {
     "@types/axios": "^0.14.0",
+    "@types/event-source-polyfill": "^1.0.5",
     "@types/jest": "^29.5.12",
     "@types/mongodb": "^4.0.7",
     "@types/node": "^22.5.4",

package/src/client/client.ts

@@ -0,0 +1,85 @@
+import axios, { AxiosInstance, AxiosRequestConfig } from 'axios';
+import { Logger } from 'winston';
+import { LaplaceConfiguration } from '../utilities/configuration';
+import { EventSourcePolyfill } from 'event-source-polyfill';
+
+
+export class Client {
+  private cli: AxiosInstance;
+  private baseUrl: string;
+  private apiKey: string;
+  private logger: Logger;
+
+  constructor(cfg: LaplaceConfiguration, logger: Logger) {
+    this.cli = axios.create();
+    this.baseUrl = cfg.baseURL;
+    this.apiKey = cfg.apiKey;
+    this.logger = logger;
+  }
+
+  async sendRequest<T>(config: AxiosRequestConfig): Promise<T> {
+    try {
+      const response = await this.cli.request<T>({
+        ...config,
+        baseURL: this.baseUrl,
+        headers: {
+          ...config.headers,
+          Authorization: `Bearer ${this.apiKey}`,
+        },
+      });
+
+      return response.data;
+    } catch (error) {
+      if (axios.isAxiosError(error) && error.response) {
+        throw new Error(`Unexpected status code: ${error.response.status}, body: ${JSON.stringify(error.response.data)}`);
+      }
+      throw error;
+    }
+  }
+
+  sendSSERequest<T>(url: string): { events: AsyncIterable<T>, cancel: () => void } {
+    const eventSource = new EventSourcePolyfill(url, {
+      headers: {
+        Accept: 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        Connection: 'keep-alive',
+        Authorization: `Bearer ${this.apiKey}`,
+      },
+    });
+
+    const events: AsyncIterable<T> = {
+      async *[Symbol.asyncIterator]() {
+        try {
+          while (true) {
+            yield await new Promise<T>((resolve, reject) => {
+              eventSource.onmessage = (event) => {
+                try {
+                  const data = JSON.parse(event.data);
+                  resolve(data);
+                } catch (error) {
+                  reject(new Error(`Error parsing event data: ${error}`));
+                }
+              };
+
+              eventSource.onerror = (event) => {
+                reject(new Error(`SSE error: ${JSON.stringify(event)}`));
+              };
+            });
+          }
+        } finally {
+          eventSource.close();
+        }
+      },
+    };
+
+    const cancel = () => {
+      eventSource.close();
+    };
+
+    return { events, cancel };
+  }
+}
+
+export function createClient(cfg: LaplaceConfiguration, logger: Logger): Client {
+  return new Client(cfg, logger);
+}

package/src/client/financial_fundamentals.ts

@@ -0,0 +1,81 @@
+import { Client } from './client';
+import { Region } from './collections';
+
+export interface StockDividend {
+  date: Date;
+  dividendAmount: number;
+  dividendRatio: number;
+  netDividendAmount: number;
+  netDividendRatio: number;
+  priceThen: number;
+}
+
+export interface StockStats {
+  previousClose: number;
+  ytdReturn: number;
+  yearlyReturn: number;
+  marketCap: number;
+  peRatio: number;
+  pbRatio: number;
+  yearLow: number;
+  yearHigh: number;
+  threeYear: number;
+  fiveYear: number;
+  symbol: string;
+}
+
+export enum StockStatsKey {
+  PreviousClose = 'previous_close',
+  YtdReturn = 'ytd_return',
+  YearlyReturn = 'yearly_return',
+  MarketCap = 'market_cap',
+  FK = 'fk',
+  PDDD = 'pddd',
+  YearLow = 'year_low',
+  YearHigh = 'year_high',
+  ThreeYearReturn = '3_year_return',
+  FiveYearReturn = '5_year_return',
+  LatestPrice = 'latest_price'
+}
+
+export interface TopMover {
+  symbol: string;
+  percentChange: number;
+}
+
+export class FinancialFundamentalsClient {
+  constructor(private client: Client) {}
+
+  async getStockDividends(symbol: string, region: Region): Promise<StockDividend[]> {
+    const url = new URL(`${this.client['baseUrl']}/api/v1/stock/dividends`);
+    url.searchParams.append('symbol', symbol);
+    url.searchParams.append('region', region);
+
+    return this.client.sendRequest<StockDividend[]>({
+      method: 'GET',
+      url: url.toString(),
+    });
+  }
+
+  async getStockStats(symbols: string[], keys: StockStatsKey[], region: Region): Promise<StockStats[]> {
+    const url = new URL(`${this.client['baseUrl']}/api/v1/stock/stats`);
+    url.searchParams.append('symbols', symbols.join(','));
+    url.searchParams.append('region', region);
+    url.searchParams.append('keys', keys.join(','));
+
+    return this.client.sendRequest<StockStats[]>({
+      method: 'GET',
+      url: url.toString(),
+    });
+  }
+
+  async getTopMovers(region: Region): Promise<TopMover[]> {
+    const url = new URL(`${this.client['baseUrl']}/api/v1/stock/top-movers`);
+    url.searchParams.append('region', region);
+
+    return this.client.sendRequest<TopMover[]>({
+      method: 'GET',
+      url: url.toString(),
+    });
+  }
+}

package/src/client/live_price.ts

@@ -0,0 +1,49 @@
+import { Client } from './client';
+import { v4 as uuidv4 } from 'uuid';
+
+export enum Region {
+  BIST = 'BIST',
+  US = 'US',
+  // Add other regions as needed
+}
+
+async function* getLivePrice<T>(
+  client: Client,
+  symbols: string[],
+  region: Region
+): AsyncGenerator<T, void, undefined> {
+  const streamId = uuidv4();
+  const url = `${client['baseUrl']}/api/v1/stock/price/live?filter=${symbols.join(',')}&region=${region}&stream=${streamId}`;
+
+  const { events, cancel } = client.sendSSERequest<T>(url);
+
+  try {
+    yield* events;
+  } finally {
+    cancel();
+  }
+}
+
+export interface BISTStockLiveData {
+  s: string;  // Symbol
+  ch: number; // DailyPercentChange
+  p: number;  // ClosePrice
+}
+
+export interface USStockLiveData {
+  s: string;  // Symbol
+  bp: number; // BidPrice
+  ap: number; // AskPrice
+}
+
+export class LivePriceClient {
+  constructor(private client: Client) {}
+
+  getLivePriceForBIST(symbols: string[], region: Region): AsyncGenerator<BISTStockLiveData, void, undefined> {
+    return getLivePrice<BISTStockLiveData>(this.client, symbols, region);
+  }
+
+  getLivePriceForUS(symbols: string[], region: Region): AsyncGenerator<USStockLiveData, void, undefined> {
+    return getLivePrice<USStockLiveData>(this.client, symbols, region);
+  }
+}

package/{test → src/test}/client_test_suite.ts

@@ -3,7 +3,7 @@ import * as dotenv from 'dotenv';
 import { findModuleRoot } from '../utilities/fs';
 import { loadGlobal, LaplaceConfiguration } from '../utilities/configuration';
 
-const testConfig = './utilities/test.env';
+const testConfig = './src/utilities/test.env';
 
 class ClientTestSuite {
   config: LaplaceConfiguration | null = null;

package/src/test/financial_fundamentals.test.ts

@@ -0,0 +1,52 @@
+import { Logger } from 'winston';
+import { LaplaceConfiguration } from '../utilities/configuration';
+import { Client, createClient } from '../client/client';
+import { FinancialFundamentalsClient } from '../client/financial_fundamentals';
+import { Region } from '../client/collections';
+import { StockStatsKey } from '../client/financial_fundamentals';
+import './client_test_suite';
+
+describe('FinancialFundamentals', () => {
+  let client: Client;
+  let stockClient: FinancialFundamentalsClient;
+
+  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;
+
+    client = createClient(config, logger);
+    stockClient = new FinancialFundamentalsClient(client);
+  });
+
+  test('GetStockDividends', async () => {
+    const resp = await stockClient.getStockDividends('TUPRS', Region.Tr);
+    expect(resp).not.toBeEmpty();
+  });
+
+  test('GetStockStats', async () => {
+    const resp = await stockClient.getStockStats(['TUPRS'], [
+      StockStatsKey.PreviousClose,
+      StockStatsKey.YtdReturn,
+      StockStatsKey.YearlyReturn,
+      StockStatsKey.MarketCap,
+      StockStatsKey.FK,
+      StockStatsKey.PDDD,
+      StockStatsKey.YearLow,
+      StockStatsKey.YearHigh,
+      StockStatsKey.ThreeYearReturn,
+      StockStatsKey.FiveYearReturn,
+      StockStatsKey.LatestPrice,
+    ], Region.Tr);
+    expect(resp).not.toBeEmpty();
+  });
+
+  test('GetTopMovers', async () => {
+    const resp = await stockClient.getTopMovers(Region.Tr);
+    expect(resp).not.toBeEmpty();
+  });
+});

package/src/test/live_price.test.ts

@@ -0,0 +1,58 @@
+import { Logger } from 'winston';
+import { LaplaceConfiguration } from '../utilities/configuration';
+import { Client, createClient } from '../client/client';
+import { LivePriceClient, Region, BISTStockLiveData, USStockLiveData } from '../client/live_price';
+import './client_test_suite';
+
+describe('LivePrice', () => {
+  let client: Client;
+  let livePriceClient: LivePriceClient;
+
+  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;
+
+    client = createClient(config, logger);
+    livePriceClient = new LivePriceClient(client);
+  });
+
+  const testLivePrice = async (
+    symbols: string[],
+    region: Region,
+    getLivePriceFunc: (symbols: string[], region: Region) => AsyncGenerator<BISTStockLiveData | USStockLiveData, void, unknown>
+  ) => {
+    const livePriceGenerator = getLivePriceFunc.call(livePriceClient, symbols, region);
+    let livePriceCount = 0;
+
+    jest.setTimeout(10000); // 10 seconds timeout
+
+    try {
+      for await (const livePrice of livePriceGenerator) {
+        expect(livePrice).not.toBeEmpty();
+        livePriceCount++;
+        if (livePriceCount > 3) {
+          break;
+        }
+      }
+    } catch (error) {
+      throw new Error(`Error occurred during live price retrieval: ${error}`);
+    }
+
+    expect(livePriceCount).toBeGreaterThan(0);
+  };
+
+  test('BISTLivePrice', async () => {
+    const symbols = ['TUPRS', 'SASA', 'THYAO', 'GARAN', 'YKBN'];
+    await testLivePrice(symbols, Region.BIST, livePriceClient.getLivePriceForBIST);
+  });
+
+  test('USLivePrice', async () => {
+    const symbols = ['AAPL', 'GOOGL', 'MSFT', 'AMZN', 'META'];
+    await testLivePrice(symbols, Region.US, livePriceClient.getLivePriceForUS);
+  });
+});

package/tsconfig.json

@@ -6,8 +6,12 @@
     "strict": true,
     "esModuleInterop": true,
     "types": ["jest", "node"],
-    "typeRoots": ["./node_modules/@types", "./types"]
+    "moduleResolution": "node",
+    "typeRoots": ["./node_modules/@types", "./src/types"]
   },
-  "include": ["src/**/*", "jest.setup.ts"],
-  "exclude": ["node_modules", "**/*.spec.ts"]
+  "include": ["src/**/*", "src/jest.setup.ts"],
+  "exclude": ["node_modules", "**/*.spec.ts"],
+  "paths": {
+    "@/*": ["src/*"]
+  }
 }

package/client/client.ts

@@ -1,41 +0,0 @@
-import axios, { AxiosInstance, AxiosRequestConfig } from 'axios';
-import { Logger } from 'winston';
-import { LaplaceConfiguration } from '../utilities/configuration';
-
-export class Client {
-  private cli: AxiosInstance;
-  private baseUrl: string;
-  private apiKey: string;
-  private logger: Logger;
-
-  constructor(cfg: LaplaceConfiguration, logger: Logger) {
-    this.cli = axios.create();
-    this.baseUrl = cfg.baseURL;
-    this.apiKey = cfg.apiKey;
-    this.logger = logger;
-  }
-
-  async sendRequest<T>(config: AxiosRequestConfig): Promise<T> {
-    try {
-      const response = await this.cli.request<T>({
-        ...config,
-        baseURL: this.baseUrl,
-        headers: {
-          ...config.headers,
-          Authorization: `Bearer ${this.apiKey}`,
-        },
-      });
-
-      return response.data;
-    } catch (error) {
-      if (axios.isAxiosError(error) && error.response) {
-        throw new Error(`Unexpected status code: ${error.response.status}, body: ${JSON.stringify(error.response.data)}`);
-      }
-      throw error;
-    }
-  }
-}
-
-export function createClient(cfg: LaplaceConfiguration, logger: Logger): Client {
-  return new Client(cfg, logger);
-}