JSPM

  • Created
  • Published
  • Downloads 218
  • Score
    100M100P100Q79903F
  • License ISC

Client library for Laplace API for the US stock market and BIST (Istanbul stock market) fundamental financial data.

Package Exports

    This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (laplace-api) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

    Readme

    Laplace TypeScript/JavaScript SDK

    Node.js Version TypeScript License npm version

    The official TypeScript/JavaScript SDK for the Laplace stock data platform. Get easy access to stock data, collections, financials, funds, and AI-powered insights.

    Features

    • ๐Ÿš€ Easy to use: Simple, intuitive API with TypeScript/JavaScript idioms
    • ๐Ÿ“Š Comprehensive data: Stocks, collections, financials, funds, and AI insights
    • ๐Ÿ”ง Well-typed: Full TypeScript type safety with comprehensive interfaces
    • ๐Ÿงช Well-tested: Comprehensive test coverage with real API integration
    • ๐ŸŒ Multi-region: Support for US and Turkish markets
    • โšก Fast: High-performance HTTP requests
    • ๐Ÿ“š Well-documented: Complete documentation for all public methods
    • ๐Ÿ”„ Real-time: Live price streaming with Server-Sent Events

    Installation

    npm install laplace-api-js

    Quick Start

    import { createClient } from "laplace-api-js";
    import { LaplaceConfiguration } from "laplace-api-js";
    import { Logger } from "winston";
    
    // Initialize the client
    const config: LaplaceConfiguration = {
      apiKey: "your-api-key-here",
      baseURL: "https://api.laplace.finfree.co",
    };
    
    const logger: Logger = {
      info: console.log,
      error: console.error,
      warn: console.warn,
      debug: console.log,
    } as Logger;
    
    const client = createClient(config, logger);
    
    // Get stock details
    async function getStockDetails() {
      try {
        const stock = await client.getStockDetailBySymbol(
          "AAPL",
          "equity",
          "us",
          "en"
        );
        console.log(`${stock.name}: ${stock.description}`);
      } catch (error) {
        console.error("Error fetching stock:", error);
      }
    }
    
    // Get all stocks in a region
    async function getAllStocks() {
      try {
        const stocks = await client.getAllStocks("us", 1, 10);
        stocks.forEach((stock) => {
          console.log(`${stock.symbol}: ${stock.name}`);
        });
      } catch (error) {
        console.error("Error fetching stocks:", error);
      }
    }
    
    // Get collections
    async function getCollections() {
      try {
        const collections = await client.getAllCollections("tr", "en");
        collections.forEach((collection) => {
          console.log(`${collection.title}: ${collection.numStocks} stocks`);
        });
      } catch (error) {
        console.error("Error fetching collections:", error);
      }
    }
    
    // Get live price data
    async function getLivePrices() {
      try {
        const liveClient = client.getLivePriceForBIST(["THYAO", "GARAN"]);
    
        for await (const data of liveClient.receive()) {
          console.log("Live price:", data);
          break; // Get first data and exit
        }
    
        liveClient.close();
      } catch (error) {
        console.error("Error getting live prices:", error);
      }
    }

    API Reference

    Stocks Client

    // Get all stocks with pagination
    const stocks = await client.getAllStocks("us", 1, 10);
    
    // Get stock detail by symbol
    const stock = await client.getStockDetailBySymbol("AAPL", "equity", "us", "en");
    
    // Get stock detail by ID
    const stock = await client.getStockDetailByID("stock-id", "en");
    
    // Get historical prices
    const prices = await client.getHistoricalPrices(["AAPL", "GOOGL"], "us", [
      "1d",
      "1w",
    ]);
    
    // Get historical prices with custom interval
    const prices = await client.getCustomHistoricalPrices(
      "AAPL",
      "us",
      "2024-01-01",
      "2024-01-31",
      "1m",
      true
    );
    
    // Get tick rules (Turkey only)
    const rules = await client.getTickRules("THYAO", "tr");
    
    // Get restrictions (Turkey only)
    const restrictions = await client.getStockRestrictions("THYAO", "tr");

    Collections Client

    // Get all collections
    const collections = await client.getAllCollections("tr", "en");
    
    // Get collection detail
    const detail = await client.getCollectionDetail("collection-id", "tr", "en");
    
    // Get themes
    const themes = await client.getAllThemes("tr", "en");
    
    // Get theme detail
    const themeDetail = await client.getThemeDetail("theme-id", "tr", "en");
    
    // Get industries
    const industries = await client.getAllIndustries("tr", "en");
    
    // Get industry detail
    const industryDetail = await client.getIndustryDetail(
      "industry-id",
      "tr",
      "en"
    );
    
    // Get sectors
    const sectors = await client.getAllSectors("tr", "en");
    
    // Get sector detail
    const sectorDetail = await client.getSectorDetail("sector-id", "tr", "en");

    Funds Client

    // Get all funds
    const funds = await client.getFunds("tr", 1, 10);
    
    // Get fund statistics
    const stats = await client.getFundStats("fund-symbol", "tr");
    
    // Get fund distribution
    const distribution = await client.getFundDistribution("fund-symbol", "tr");
    
    // Get historical fund prices
    const prices = await client.getHistoricalFundPrices("fund-symbol", "tr", "1y");

    Financial Data Client

    // Get financial ratios
    const ratios = await client.getHistoricalRatios(
      "AAPL",
      ["pe-ratio"],
      "us",
      "en"
    );
    
    // Get financial ratio comparisons
    const comparisons = await client.getFinancialRatioComparison(
      "AAPL",
      "us",
      "sector"
    );
    
    // Get stock dividends
    const dividends = await client.getStockDividends("AAPL", "us");
    
    // Get stock statistics
    const stats = await client.getStockStats(["AAPL", "GOOGL"], "us");
    
    // Get top movers
    const movers = await client.getTopMovers(
      "us",
      1,
      10,
      "gainers",
      "stock",
      "equity"
    );

    Live Price Client

    // Get live prices for BIST stocks
    const bistClient = client.getLivePriceForBIST(["THYAO", "GARAN"]);
    
    // Get live prices for US stocks
    const usClient = client.getLivePriceForUS(["AAPL", "GOOGL"]);
    
    // Receive live data
    for await (const data of bistClient.receive()) {
      console.log("Received BIST data:", data);
      // data.s - symbol, data.p - price, data.ch - change, data.d - date
    }
    
    // Subscribe to different symbols
    await bistClient.subscribe(["AKBNK", "EREGL"]);
    
    // Close connection
    bistClient.close();

    Brokers Client

    // Get all brokers
    const brokers = await client.getBrokers("tr", 1, 10);
    
    // Get market stocks with broker statistics
    const marketStocks = await client.getMarketStocks(
      "tr",
      "netAmount",
      "desc",
      "2024-01-01",
      "2024-01-31",
      1,
      10
    );
    
    // Get brokers by stock
    const brokersByStock = await client.getBrokersByStock(
      "THYAO",
      "tr",
      "netAmount",
      "desc",
      "2024-01-01",
      "2024-01-31",
      1,
      10
    );

    Search Client

    // Search across stocks, collections, sectors, and industries
    const results = await client.search(
      "technology",
      ["stock", "collection"],
      "us",
      "en"
    );

    WebSocket Client

    // Server Side
    // Initialize LivePriceClient for server side use
    const livePriceClient = new LivePriceClient(config, logger);
    
    // Retrieve a websocket connection URL for the client, pass the URL to the client
    const wsURL = await livePriceClient.getClientWebsocketUrl('external-user-id', [LivePriceFeed.LiveBist])
    
    // Client Side
    // Client side retrieves the websocket connection URL from the server as wsURL
    // Create WebSocket client for real-time data
    const webSocketClient = new LivePriceWebSocketClient();
    
    // Connect to WebSocket
    await webSocketClient.connect(wsURL);
    
    // Subscribe to live price feeds
    const unsubscribe = webSocketClient.subscribe(
      ["THYAO", "GARAN"],
      LivePriceFeed.LiveBist,
      (data) => {
        console.log("Received live data:", data);
      }
    );
    
    // Close connection
    await webSocketClient.close();
    
    // Server Side
    // Use livePriceClient.getWebsocketUsageForMonth for getting a report on websocket client usage
    const usage = await livePriceClient.getWebsocketUsageForMonth('8', '2025', LivePriceFeed.LiveBist);

    Capital Increase Client

    // Get all capital increases
    const increases = await client.getAllCapitalIncreases(1, 10, "tr");
    
    // Get capital increases for a specific instrument
    const instrumentIncreases = await client.getCapitalIncreasesForInstrument(
      "THYAO",
      1,
      10,
      "tr"
    );
    
    // Get active rights for an instrument
    const rights = await client.getActiveRightsForInstrument(
      "THYAO",
      "2024-01-15",
      "tr"
    );

    Custom Themes Client

    // Get all custom themes
    const themes = await client.getAllCustomThemes("en");
    
    // Get custom theme detail
    const themeDetail = await client.getCustomThemeDetail("theme-id", "en", null);
    
    // Create a custom theme
    const id = await client.createCustomTheme({
      title: { en: "My Tech Portfolio" },
      description: { en: "Technology stocks portfolio" },
      region: ["us"],
      stocks: ["stock-id-1", "stock-id-2"],
      status: "active",
    });
    
    // Update a custom theme
    await client.updateCustomTheme(id, {
      title: { en: "Updated Tech Portfolio" },
      stockIds: ["stock-id-1", "stock-id-2"],
    });
    
    // Delete a custom theme
    await client.deleteCustomTheme(id);

    Key Insights Client

    // Get key insights for a stock
    const insights = await client.getKeyInsights("AAPL", "us");

    Supported Regions

    • US: United States stock market
    • TR: Turkey stock market (Borsa Istanbul)

    Error Handling

    import { createClient } from "laplace-api-js";
    import { LaplaceHTTPError } from "laplace-api-js";
    
    const client = createClient(config, logger);
    
    try {
      const stock = await client.getStockDetailBySymbol(
        "INVALID",
        "equity",
        "us",
        "en"
      );
    } catch (error) {
      if (error instanceof LaplaceHTTPError) {
        console.log(`API Error: ${error.message}`);
        console.log(`Status Code: ${error.httpStatus}`);
      } else {
        console.log(`Error: ${error}`);
      }
    }

    Authentication

    Get your API key from the Laplace platform and initialize the client:

    import { createClient } from "laplace-api-js";
    import { LaplaceConfiguration } from "laplace-api-js";
    
    const config: LaplaceConfiguration = {
      apiKey: "your-api-key-here",
      baseURL: "https://api.laplace.finfree.co",
    };
    
    const client = createClient(config, logger);

    Configuration

    You can also load configuration from environment variables:

    import { loadGlobal } from "laplace-api-js";
    
    const config = loadGlobal();
    const client = createClient(config, logger);

    Environment variables:

    • API_KEY: Your API key
    • BASE_URL: API base URL

    Development

    Setup

    git clone https://github.com/Laplace-Analytics/laplace-api-js.git
    cd laplace-api-js
    npm install

    Building

    # Build the project
    npm run build
    
    # Build with type checking
    npm run build:check

    Requirements

    • Node.js 18+
    • TypeScript 5.0+

    Documentation

    Full API documentation is available at laplace.finfree.co/en/docs

    License

    This project is licensed under the MIT License - see the LICENSE file for details.