laplace-api 1.0.0

package/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 canturkay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,2 @@
+# laplace-api-js
+ Client library for Laplace API for the US stock market and BIST (Istanbul stock market) fundamental financial data.

package/client/client.ts

@@ -0,0 +1,41 @@
+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);
+}

package/client/collections.ts

@@ -0,0 +1,97 @@
+import { Client } from './client';
+import { Stock } from './stocks';
+
+export enum CollectionType {
+  Sector = 'sector',
+  Industry = 'industry',
+  Theme = 'theme',
+  CustomTheme = 'custom-theme',
+  Collection = 'collection',
+}
+
+export enum Region {
+  Tr = 'tr',
+  Us = 'us',
+}
+
+export enum Locale {
+  Tr = 'tr',
+  En = 'en',
+}
+
+export interface Collection {
+  id: string;
+  title: string;
+  description: string;
+  region: Region[];
+  assetClass: string;
+  imageUrl: string;
+  avatarUrl: string;
+  numStocks: number;
+  image: string;
+  order: number;
+  status?: string;
+  metaData?: Record<string, any>;
+}
+
+export interface CollectionDetail extends Collection {
+  stocks: Stock[];
+}
+
+export class CollectionClient extends Client {
+  private async getAllCollectionsPrivate(collectionType: CollectionType, region: Region, locale: Locale): Promise<Collection[]> {
+    return this.sendRequest<Collection[]>({
+      method: 'GET',
+      url: `/api/v1/${collectionType}`,
+      params: { region, locale },
+    });
+  }
+
+  private async getCollectionDetailPrivate(id: string, collectionType: CollectionType, region: Region, locale: Locale): Promise<CollectionDetail> {
+    return this.sendRequest<CollectionDetail>({
+      method: 'GET',
+      url: `/api/v1/${collectionType}/${id}`,
+      params: { region, locale },
+    });
+  }
+
+  async getAllSectors(region: Region, locale: Locale): Promise<Collection[]> {
+    return this.getAllCollectionsPrivate(CollectionType.Sector, region, locale);
+  }
+
+  async getAllIndustries(region: Region, locale: Locale): Promise<Collection[]> {
+    return this.getAllCollectionsPrivate(CollectionType.Industry, region, locale);
+  }
+
+  async getAllThemes(region: Region, locale: Locale): Promise<Collection[]> {
+    return this.getAllCollectionsPrivate(CollectionType.Theme, region, locale);
+  }
+
+  async getAllCustomThemes(region: Region, locale: Locale): Promise<Collection[]> {
+    return this.getAllCollectionsPrivate(CollectionType.CustomTheme, region, locale);
+  }
+
+  async getAllCollections(region: Region, locale: Locale): Promise<Collection[]> {
+    return this.getAllCollectionsPrivate(CollectionType.Collection, region, locale);
+  }
+
+  async getSectorDetail(id: string, region: Region, locale: Locale): Promise<CollectionDetail> {
+    return this.getCollectionDetailPrivate(id, CollectionType.Sector, region, locale);
+  }
+
+  async getIndustryDetail(id: string, region: Region, locale: Locale): Promise<CollectionDetail> {
+    return this.getCollectionDetailPrivate(id, CollectionType.Industry, region, locale);
+  }
+
+  async getThemeDetail(id: string, region: Region, locale: Locale): Promise<CollectionDetail> {
+    return this.getCollectionDetailPrivate(id, CollectionType.Theme, region, locale);
+  }
+
+  async getCustomThemeDetail(id: string, region: Region, locale: Locale): Promise<CollectionDetail> {
+    return this.getCollectionDetailPrivate(id, CollectionType.CustomTheme, region, locale);
+  }
+
+  async getCollectionDetail(id: string, region: Region, locale: Locale): Promise<CollectionDetail> {
+    return this.getCollectionDetailPrivate(id, CollectionType.Collection, region, locale);
+  }
+}

package/client/search.ts

@@ -0,0 +1,51 @@
+import { Client } from './client';
+import { Region, Locale } from './collections';
+
+export enum SearchType {
+  Stock = 'stock',
+  Collection = 'collection',
+  Sector = 'sector',
+  Industry = 'industry',
+}
+
+export interface SearchResponseStock {
+  id: string;
+  name: string;
+  symbol: string;
+  region: string;
+  assetClass: string;
+  assetType: string;
+}
+
+export interface SearchResponseCollection {
+  id: string;
+  title: string;
+  region: string[];
+  assetClass: string;
+  imageUrl: string;
+  avatarUrl: string;
+}
+
+export interface SearchResponse {
+  stocks: SearchResponseStock[];
+  collections: SearchResponseCollection[];
+  sectors: SearchResponseCollection[];
+  industries: SearchResponseCollection[];
+}
+
+export class SearchClient extends Client {
+  async search(query: string, types: SearchType[], region: Region, locale: Locale): Promise<SearchResponse> {
+    const typesStr = types.join(',');
+
+    return this.sendRequest<SearchResponse>({
+      method: 'GET',
+      url: '/api/v1/search',
+      params: {
+        filter: query,
+        types: typesStr,
+        region,
+        locale,
+      },
+    });
+  }
+}

package/client/stocks.ts

@@ -0,0 +1,113 @@
+import { Client } from './client';
+import { Region, Locale } from './collections';
+
+export enum AssetType {
+  Stock = 'stock',
+  Forex = 'forex',
+  Index = 'index',
+  Etf = 'etf',
+  Commodity = 'commodity',
+}
+
+export enum AssetClass {
+  Equity = 'equity',
+  Crypto = 'crypto',
+}
+
+export enum HistoricalPricePeriod {
+  OneDay = '1D',
+  OneWeek = '1W',
+  OneMonth = '1M',
+  ThreeMonth = '3M',
+  OneYear = '1Y',
+  TwoYear = '2Y',
+  ThreeYear = '3Y',
+  FiveYear = '5Y',
+}
+
+export interface Stock {
+  id: string;
+  assetType: AssetType;
+  name: string;
+  symbol: string;
+  sectorId: string;
+  industryId: string;
+  updatedDate: string;
+  dailyChange?: number;
+}
+
+export interface LocaleString {
+  [key: string]: string;
+}
+
+export interface StockDetail {
+  id: string;
+  assetType: AssetType;
+  assetClass: AssetClass;
+  name: string;
+  symbol: string;
+  description: string;
+  localized_description: LocaleString;
+  region: string;
+  sectorId: string;
+  industryId: string;
+  updatedDate: string;
+}
+
+export interface PriceDataPoint {
+  d: number;
+  c: number;
+  h: number;
+  l: number;
+  o: number;
+}
+
+export interface StockPriceGraph {
+  symbol: string;
+  '1D': PriceDataPoint[];
+  '1W': PriceDataPoint[];
+  '1M': PriceDataPoint[];
+  '3M': PriceDataPoint[];
+  '1Y': PriceDataPoint[];
+  '2Y': PriceDataPoint[];
+  '3Y': PriceDataPoint[];
+  '5Y': PriceDataPoint[];
+}
+
+export class StockClient extends Client {
+  async getAllStocks(region: Region): Promise<Stock[]> {
+    return this.sendRequest<Stock[]>({
+      method: 'GET',
+      url: '/api/v1/stock/all',
+      params: { region },
+    });
+  }
+
+  async getStockDetailById(id: string, locale: Locale): Promise<StockDetail> {
+    return this.sendRequest<StockDetail>({
+      method: 'GET',
+      url: `/api/v1/stock/${id}`,
+      params: { locale },
+    });
+  }
+
+  async getStockDetailBySymbol(symbol: string, assetClass: AssetClass, region: Region, locale: Locale): Promise<StockDetail> {
+    return this.sendRequest<StockDetail>({
+      method: 'GET',
+      url: '/api/v1/stock/detail',
+      params: { symbol, asset_class: assetClass, region, locale },
+    });
+  }
+
+  async getHistoricalPrices(symbols: string[], region: Region, keys: HistoricalPricePeriod[]): Promise<StockPriceGraph[]> {
+    return this.sendRequest<StockPriceGraph[]>({
+      method: 'GET',
+      url: '/api/v1/stock/price',
+      params: {
+        symbols: symbols.join(','),
+        region,
+        keys: keys.join(','),
+      },
+    });
+  }
+}

package/jest.config.js

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

package/jest.setup.ts

@@ -0,0 +1,29 @@
+import 'jest';
+
+declare global {
+  namespace jest {
+    interface Matchers<R> {
+      toBeEmpty(): R;
+    }
+  }
+}
+
+expect.extend({
+  toBeEmpty(received: any) {
+    if (Array.isArray(received) || typeof received === 'string') {
+      return {
+        message: () => `expected ${received} to be empty`,
+        pass: received.length === 0,
+      };
+    } else if (typeof received === 'object' && received !== null) {
+      return {
+        message: () => `expected ${received} to be empty`,
+        pass: Object.keys(received).length === 0,
+      };
+    }
+    return {
+      message: () => `expected ${received} to be empty`,
+      pass: false,
+    };
+  },
+});

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "laplace-api",
+  "version": "1.0.0",
+  "description": "Client library for Laplace API for the US stock market and BIST (Istanbul stock market) fundamental financial data.",
+  "main": "index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "jest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Laplace-Analytics/laplace-api-js.git"
+  },
+  "keywords": [
+    "finance",
+    "stock",
+    "market",
+    "stock",
+    "price",
+    "financial",
+    "data",
+    "price",
+    "chart",
+    "price",
+    "graph",
+    "stock",
+    "data",
+    "BIST"
+  ],
+  "author": "Laplace Analytics",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/Laplace-Analytics/laplace-api-js/issues"
+  },
+  "homepage": "https://github.com/Laplace-Analytics/laplace-api-js#readme",
+  "dependencies": {
+    "axios": "^1.7.7",
+    "dotenv": "^16.4.5",
+    "envalid": "^8.0.0",
+    "mongodb": "^6.8.0",
+    "winston": "^3.14.2"
+  },
+  "devDependencies": {
+    "@types/axios": "^0.14.0",
+    "@types/jest": "^29.5.12",
+    "@types/mongodb": "^4.0.7",
+    "@types/node": "^22.5.4",
+    "@types/winston": "^2.4.4",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.5.4"
+  }
+}

package/test/client.test.ts

@@ -0,0 +1,53 @@
+import { Logger } from 'winston';
+import { LaplaceConfiguration } from '../utilities/configuration';
+import { Client, createClient } from '../client/client';
+import './client_test_suite';
+
+// Assuming these are defined elsewhere in your project
+enum Region { Tr = 'tr' }
+enum Locale { Tr = 'tr' }
+
+class LaplaceClientTestSuite {
+  private config: LaplaceConfiguration;
+
+  constructor(config: LaplaceConfiguration) {
+    this.config = config;
+  }
+
+  async testClient() {
+    const logger: Logger = {
+      info: jest.fn(),
+      error: jest.fn(),
+      warn: jest.fn(),
+      debug: jest.fn(),
+    } as unknown as Logger;
+
+    const client = createClient(this.config, logger);
+
+    const res = await client.sendRequest({
+      method: 'GET',
+      url: '/api/v1/industry',
+      params: {
+        region: Region.Tr,
+        locale: Locale.Tr,
+      },
+    });
+
+    expect(res).toBeTruthy();
+    expect(res).not.toEqual({});
+  }
+}
+
+describe('LaplaceClient', () => {
+  let testSuite: LaplaceClientTestSuite;
+
+  beforeAll(() => {
+    // Assuming global.testSuite is set up as in the previous example
+    const config = (global as any).testSuite.config;
+    testSuite = new LaplaceClientTestSuite(config);
+  });
+
+  it('should make a successful request', async () => {
+    await testSuite.testClient();
+  });
+});

package/test/client_test_suite.ts

@@ -0,0 +1,51 @@
+import * as path from 'path';
+import * as dotenv from 'dotenv';
+import { findModuleRoot } from '../utilities/fs';
+import { loadGlobal, LaplaceConfiguration } from '../utilities/configuration';
+
+const testConfig = './utilities/test.env';
+
+class ClientTestSuite {
+  config: LaplaceConfiguration | null = null;
+
+  async setUp(): Promise<void> {
+    try {
+      const repoRoot = await findModuleRoot();
+      const configPath = path.join(repoRoot, testConfig);
+      
+      dotenv.config({ path: configPath });
+      
+      this.config = loadGlobal(configPath);
+
+      if (!this.config) {
+        throw new Error('Config is not set');
+      }
+      
+      if (!this.config.apiKey) {
+        throw new Error('API key is not set');
+      }
+      
+      if (!this.config.baseURL) {
+        throw new Error('API base URL is not set');
+      }
+    } catch (error) {
+      throw new Error(`Setup failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+}
+
+// Jest beforeAll hook to set up the test suite
+beforeAll(async () => {
+  const suite = new ClientTestSuite();
+  await suite.setUp();
+  (global as any).testSuite = suite;
+});
+
+// Example test
+test('Config is properly loaded', () => {
+  expect((global as any).testSuite.config).toBeTruthy();
+  expect((global as any).testSuite.config?.apiKey).toBeTruthy();
+  expect((global as any).testSuite.config?.baseURL).toBeTruthy();
+});
+
+export { ClientTestSuite };

package/test/collections.test.ts

@@ -0,0 +1,36 @@
+import { Logger } from 'winston';
+import { LaplaceConfiguration } from '../utilities/configuration';
+import { CollectionClient, Region, Locale } from '../client/collections';
+import './client_test_suite';
+
+describe('Collections', () => {
+  let client: CollectionClient;
+
+  beforeAll(() => {
+    // Assuming global.testSuite is set up as in the previous example
+    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 = new CollectionClient(config, logger);
+  });
+
+  test('GetAllIndustries', async () => {
+    const resp = await client.getAllIndustries(Region.Tr, Locale.Tr);
+    expect(resp).not.toBeEmpty();
+  });
+
+  test('GetIndustryDetails', async () => {
+    const resp = await client.getIndustryDetail("65533e441fa5c7b58afa0944", Region.Tr, Locale.Tr);
+    expect(resp).not.toBeEmpty();
+  });
+
+  test('GetSectorDetails', async () => {
+    const resp = await client.getSectorDetail("65533e047844ee7afe9941b9", Region.Tr, Locale.Tr);
+    expect(resp).not.toBeEmpty();
+  });
+});

package/test/search.test.ts

@@ -0,0 +1,43 @@
+import { Logger } from 'winston';
+import { LaplaceConfiguration } from '../utilities/configuration';
+import { SearchClient, SearchType } from '../client/search';
+import { Region, Locale } from '../client/collections';
+import './client_test_suite';
+
+
+describe('Search', () => {
+  let client: SearchClient;
+
+  beforeAll(() => {
+    // Assuming global.testSuite is set up as in the previous example
+    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 = new SearchClient(config, logger);
+  });
+
+  test('SearchStock', async () => {
+    const resp = await client.search("TUPRS", [SearchType.Stock], Region.Tr, Locale.Tr);
+    expect(resp).not.toBeEmpty();
+  });
+
+  test('SearchIndustry', async () => {
+    const resp = await client.search("Hava Taşımacılığı", [SearchType.Industry], Region.Tr, Locale.Tr);
+    expect(resp).not.toBeEmpty();
+  });
+
+  test('SearchAllTypes', async () => {
+    const resp = await client.search("Ab", [
+      SearchType.Stock,
+      SearchType.Industry,
+      SearchType.Sector,
+      SearchType.Collection
+    ], Region.Us, Locale.Tr);
+    expect(resp).not.toBeEmpty();
+  });
+});

package/test/stocks.test.ts

@@ -0,0 +1,51 @@
+import { Logger } from 'winston';
+import { LaplaceConfiguration } from '../utilities/configuration';
+import { StockClient, AssetClass, HistoricalPricePeriod } from '../client/stocks';
+import { Region, Locale } from '../client/collections';
+import './client_test_suite';
+
+
+describe('Stocks', () => {
+  let client: StockClient;
+
+  beforeAll(() => {
+    // Assuming global.testSuite is set up as in the previous example
+    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 = new StockClient(config, logger);
+  });
+
+  test('GetAllStocks', async () => {
+    const resp = await client.getAllStocks(Region.Tr);
+    expect(resp).not.toBeEmpty();
+  });
+
+  test('GetStockDetailByID', async () => {
+    const resp = await client.getStockDetailById("61dd0d6f0ec2114146342fd0", Locale.Tr);
+    expect(resp).not.toBeEmpty();
+  });
+
+  test('GetStockDetailBySymbol', async () => {
+    const resp = await client.getStockDetailBySymbol("TUPRS", AssetClass.Equity, Region.Tr, Locale.Tr);
+    expect(resp).not.toBeEmpty();
+  });
+
+  test('GetHistoricalPrices', async () => {
+    const resp = await client.getHistoricalPrices(
+      ["TUPRS", "SASA"],
+      Region.Tr,
+      [HistoricalPricePeriod.OneDay, HistoricalPricePeriod.OneWeek, HistoricalPricePeriod.OneMonth]
+    );
+    expect(resp).not.toBeEmpty();
+
+    for (const price of resp) {
+      expect(price).not.toBeEmpty();
+    }
+  });
+});

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "es6",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "types": ["jest", "node"],
+    "typeRoots": ["./node_modules/@types", "./types"]
+  },
+  "include": ["src/**/*", "jest.setup.ts"],
+  "exclude": ["node_modules", "**/*.spec.ts"]
+}

package/utilities/configuration.ts

@@ -0,0 +1,73 @@
+import * as dotenv from 'dotenv';
+import * as envalid from 'envalid';
+const { str } = envalid;
+
+export interface LaplaceConfigurationInterface {
+  baseURL: string;
+  apiKey: string;
+}
+
+export class LaplaceConfiguration implements LaplaceConfigurationInterface {
+  baseURL: string;
+  apiKey: string;
+
+  constructor({ baseURL, apiKey }: LaplaceConfigurationInterface) {
+    this.baseURL = baseURL;
+    this.apiKey = apiKey;
+  }
+
+  validate(): null | Error {
+    // Add validation logic if needed
+    return null;
+  }
+
+  applyDefaults(): null | Error {
+    // Apply default values if needed
+    return null;
+  }
+}
+
+function loadEnvironment(filename?: string): dotenv.DotenvConfigOutput {
+  if (filename) {
+    return dotenv.config({ path: filename, override: true });
+  } else {
+    return dotenv.config({ debug: false });
+  }
+}
+
+type ValidationFunc = (config: LaplaceConfiguration) => null | Error;
+
+function validationFuncRegular(config: LaplaceConfiguration): null | Error {
+  return config.validate();
+}
+
+export function loadGlobal(filename?: string, validationFunc: ValidationFunc = validationFuncRegular): LaplaceConfiguration {
+  const envLoadResult = loadEnvironment(filename);
+  if (envLoadResult.error) {
+    throw envLoadResult.error;
+  }
+
+  const env = envalid.cleanEnv(process.env, {
+    BASE_URL: str(),
+    API_KEY: str(),
+  });
+
+  const config = new LaplaceConfiguration({
+    baseURL: env.BASE_URL,
+    apiKey: env.API_KEY,
+  });
+
+  const defaultError = config.applyDefaults();
+  if (defaultError) {
+    throw defaultError;
+  }
+
+  if (validationFunc) {
+    const validationError = validationFunc(config);
+    if (validationError) {
+      throw validationError;
+    }
+  }
+
+  return config;
+}

package/utilities/fs.ts

@@ -0,0 +1,22 @@
+import * as path from 'path';
+import * as fs from 'fs/promises';
+
+// FindModuleRoot finds the relative path to the root of the project.
+export async function findModuleRoot(): Promise<string> {
+    let currentDir = process.cwd();
+
+    while (true) {
+        try {
+            await fs.access(path.join(currentDir, 'package.json'));
+            // package.json found
+            return currentDir;
+        } catch (error) {
+            const parentDir = path.dirname(currentDir);
+            if (parentDir === currentDir) {
+                // Reached the root directory
+                throw new Error('package.json file not found');
+            }
+            currentDir = parentDir;
+        }
+    }
+}

package/utilities/test.env

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