fmp-node-api 0.0.3 → 0.0.4

package/dist/index.mjs

@@ -29,8 +29,26 @@ var FMPClient = class {
     });
     return client;
   }
-  // Smart routing method
+  // Standard get method - returns raw API response
   async get(endpoint, version = "v3", params) {
+    const client = this.getClientForVersion(version);
+    try {
+      const response = await client.get(endpoint, { params });
+      return {
+        success: true,
+        data: response.data,
+        status: response.status
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error.message || "Unknown error occurred",
+        status: error.response?.status || 500
+      };
+    }
+  }
+  // Get method for single-object endpoints - unwraps single-item arrays
+  async getSingle(endpoint, version = "v3", params) {
     const client = this.getClientForVersion(version);
     try {
       const response = await client.get(endpoint, { params });
@@ -129,7 +147,7 @@ var StockEndpoints = class {
    * @returns This endpoint gives you the latest bid and ask prices for a stock, as well as the volume and last trade price in real time.
    */
   async getQuote({ symbol }) {
-    return this.client.get(`/quote/${symbol}`, "v3");
+    return this.client.getSingle(`/quote/${symbol}`, "v3");
   }
   /**
    * Get historical stock prices
@@ -147,7 +165,7 @@ var StockEndpoints = class {
     const params = {};
     if (from) params.from = from;
     if (to) params.to = to;
-    return this.client.get(`/historical-price-full/${symbol}`, "v3", params);
+    return this.client.getSingle(`/historical-price-full/${symbol}`, "v3", params);
   }
   /**
    * Get market cap
@@ -155,10 +173,8 @@ var StockEndpoints = class {
    * @param symbol - The stock symbol to get the market cap for
    * @returns The FMP Market Cap endpoint provides the current market capitalization of a company. Market cap is a measure of the size and relative importance of a company in the stock market. It is calculated by multiplying the current share price by the number of outstanding shares.
    */
-  async getMarketCap({
-    symbol
-  }) {
-    return this.client.get(`/market-capitalization/${symbol}`, "v3");
+  async getMarketCap({ symbol }) {
+    return this.client.getSingle(`/market-capitalization/${symbol}`, "v3");
   }
   /**
    * Get stock splits
@@ -166,10 +182,8 @@ var StockEndpoints = class {
    * @param symbol - The stock symbol to get the splits for
    * @returns A list of historical stock splits for publicly traded companies, including the date of the stock split, the split ratio, and the type of stock split.
    */
-  async getStockSplits({
-    symbol
-  }) {
-    return this.client.get(`/stock-split-calendar/${symbol}`, "v3");
+  async getStockSplits({ symbol }) {
+    return this.client.get(`/historical-price-full/stock_split/${symbol}`, "v3");
   }
   /**
    * Get dividend history
@@ -180,7 +194,7 @@ var StockEndpoints = class {
   async getDividendHistory({
     symbol
   }) {
-    return this.client.get(`/historical-price-full/stock_dividend/${symbol}`, "v3");
+    return this.client.getSingle(`/historical-price-full/stock_dividend/${symbol}`, "v3");
   }
 };
 
@@ -210,7 +224,7 @@ var FinancialEndpoints = class {
    * @param symbol - The stock symbol to get the balance sheet for
    * @param period - The period to get the balance sheet for (annual or quarter)
    * @param limit - The number of periods to get
-   * @returns The balance sheet is a financial statement that displays a company’s total assets, liabilities, and shareholder equity over a specific timeframe (quarterly or yearly). Investors can use this statement to determine if the company can fund its operations, meet its debt obligations, and pay a dividend.
+   * @returns The balance sheet is a financial statement that displays a company's total assets, liabilities, and shareholder equity over a specific timeframe (quarterly or yearly). Investors can use this statement to determine if the company can fund its operations, meet its debt obligations, and pay a dividend.
    */
   async getBalanceSheet({
     symbol,
@@ -228,7 +242,7 @@ var FinancialEndpoints = class {
    * @param symbol - The stock symbol to get the cash flow statement for
    * @param period - The period to get the cash flow statement for (annual or quarter)
    * @param limit - The number of periods to get
-   * @returns The cash flow statement is a financial statement that highlights how cash moves through the company, including both cash inflows and outflows. This statement shows the cash flows in 3 main categories “Operating Cash Flows”, “Investing Cash Flows”, and “Financing Cash Flows”, which help investors to understand if the company is making money or losing money by conducting business.
+   * @returns The cash flow statement is a financial statement that highlights how cash moves through the company, including both cash inflows and outflows. This statement shows the cash flows in 3 main categories "Operating Cash Flows", "Investing Cash Flows", and "Financing Cash Flows", which help investors to understand if the company is making money or losing money by conducting business.
    */
   async getCashFlowStatement({
     symbol,
@@ -351,6 +365,31 @@ var FinancialEndpoints = class {
   }) {
     return this.client.get(`/financial-growth/${symbol}?period=${period}&limit=${limit}`, "v3");
   }
+  /**
+   * Get earnings historical
+   * https://site.financialmodelingprep.com/developer/docs#earnings-historical-earnings
+   * @param symbol - The stock symbol to get the earnings historical for
+   * @param limit - The number of periods to get
+   * @returns A list of historical & upcoming earnings announcements for a specific company, including the date, estimated EPS, and actual EPS.
+   */
+  async getEarningsHistorical({
+    symbol,
+    limit = 5
+  }) {
+    return this.client.get(`/historical/earning_calendar/${symbol}?limit=${limit}`, "v3");
+  }
+  /**
+   * Get earnings surprises
+   * https://site.financialmodelingprep.com/developer/docs#earnings-surprises-earnings
+   * @param symbol - The stock symbol to get the earnings surprises for
+   * @param limit - The number of periods to get
+   * @returns A list of earnings announcements for publicly traded companies that were either positive or negative surprises. This endpoint includes the date of the earnings announcement, the estimated EPS, the actual EPS, and the earnings surprise.
+   */
+  async getEarningsSurprises({
+    symbol
+  }) {
+    return this.client.get(`/earnings-surprises/${symbol}`, "v3");
+  }
 };
 
 // src/endpoints/forex.ts
@@ -360,12 +399,18 @@ var ForexEndpoints = class {
   }
   /**
    * Get forex quote
+   * @param params - Parameters for the forex quote request
+   * @returns Forex quote data
    */
   async getQuote(params) {
     return this.client.get("/quote", "v3", params);
   }
   /**
    * Get historical forex prices
+   * @param symbol - The forex symbol to get the historical prices for
+   * @param from - The start date to get the historical prices for
+   * @param to - The end date to get the historical prices for
+   * @returns Historical forex price data
    */
   async getHistoricalPrice({
     symbol,
@@ -379,12 +424,15 @@ var ForexEndpoints = class {
   }
   /**
    * Get forex rates for a specific base currency
+   * @param baseCurrency - The base currency to get forex rates for
+   * @returns Forex rates data
    */
   async getForexRates(baseCurrency = "USD") {
     return this.client.get(`/forex/${baseCurrency}`, "v3");
   }
   /**
    * Get all forex rates
+   * @returns All forex rates data
    */
   async getAllForexRates() {
     return this.client.get("/forex", "v3");
@@ -398,12 +446,20 @@ var CryptoEndpoints = class {
   }
   /**
    * Get crypto quote
+   * https://site.financialmodelingprep.com/developer/docs#full-quote-crypto
+   * @param symbol - The crypto symbol to get the quote for
+   * @returns Crypto quote data
    */
-  async getQuote(params) {
-    return this.client.get("/quote", "v3", params);
+  async getQuote({ symbol }) {
+    return this.client.getSingle(`/quote/${symbol}`, "v3");
   }
   /**
    * Get historical crypto prices
+   * https://site.financialmodelingprep.com/developer/docs#cryptocurrency-daily-crypto
+   * @param symbol - The crypto symbol to get the historical prices for
+   * @param from - The start date to get the historical prices for
+   * @param to - The end date to get the historical prices for
+   * @returns Provides daily price data for all cryptocurrencies that are traded on exchanges around the world.
    */
   async getHistoricalPrice({
     symbol,
@@ -413,7 +469,7 @@ var CryptoEndpoints = class {
     const params = {};
     if (from) params.from = from;
     if (to) params.to = to;
-    return this.client.get(`/historical-price-full/${symbol}`, "v3", params);
+    return this.client.getSingle(`/historical-price-full/${symbol}`, "v3", params);
   }
 };
 
@@ -423,22 +479,78 @@ var ETFEndpoints = class {
     this.client = client;
   }
   /**
-   * Get ETF quote
+   * Get ETF holding dates
+   * https://site.financialmodelingprep.com/developer/docs#etf-holding-dates-etf-holdings
+   * @param symbol - The symbol of the ETF to get the holding dates for
+   * @returns The FMP ETF Holding Dates endpoint provides a list of the dates on which ETF holdings are updated. For example, an investor may want to know when an ETF's holdings are updated in order to make sure that they are still aligned with their investment goals.
    */
-  async getQuote(params) {
-    return this.client.get("/quote", "v3", params);
+  async getHoldingDates({ symbol }) {
+    const params = {};
+    if (symbol) params.symbol = symbol;
+    return this.client.get("/etf-holdings/portfolio-date", "v4", params);
+  }
+  /**
+   * Get ETF holdings
+   * https://site.financialmodelingprep.com/developer/docs#etf-holdings-etf-holdings
+   * @param symbol - The symbol of the ETF to get the holdings for
+   * @param date - The date to get the holdings for
+   * @returns The FMP ETF Holdings endpoint provides a list of all the institutional investors that own shares of an ETF. For example, an investor may want to know which ETF has the highest exposure to a particular industry or sector.
+   */
+  async getHoldings({
+    symbol,
+    date
+  }) {
+    const params = {};
+    if (symbol) params.symbol = symbol;
+    if (date) params.date = date;
+    return this.client.get("/etf-holdings", "v4", params);
+  }
+  /**
+   * Get ETF holder
+   * https://site.financialmodelingprep.com/developer/docs#etf-holder-etf-holdings
+   * @param symbol - The symbol of the ETF to get the holder for
+   * @returns This endpoint returns all stocks held by a specific ETF. Assets, share number, and weight are among the fields returned. For example you can get components of SPY, VOO and more.
+   */
+  async getHolder({ symbol }) {
+    return this.client.get(`/etf-holder/${symbol}`, "v3");
   }
   /**
    * Get ETF profile
+   * https://site.financialmodelingprep.com/developer/docs#etf-information-etf-holdings
+   * @param symbol - The symbol of the ETF to get the profile for
+   * @returns The FMP ETF Information endpoint provides basic information about an ETF, such as its ticker symbol, name, expense ratio, and asset under management. For example, an investor may want to compare the expense ratios of different ETFs to find the one that is most cost-effective.
    */
-  async getProfile(params) {
-    return this.client.get("/profile", "v3", params);
+  async getProfile({ symbol }) {
+    const params = {};
+    if (symbol) params.symbol = symbol;
+    return this.client.getSingle("/etf-info", "v4", params);
   }
   /**
-   * Get ETF holdings
+   * Get ETF sector weighting
+   * https://site.financialmodelingprep.com/developer/docs#etf-sector-weighting-etf-holdings
+   * @param symbol - The symbol of the ETF to get the sector exposure for
+   * @returns The FMP ETF Sector Weighting endpoint provides a breakdown of the percentage of an ETF's assets that are invested in each sector. For example, an investor may want to invest in an ETF that has a high exposure to the technology sector if they believe that the technology sector is poised for growth.
    */
-  async getHoldings(params) {
-    return this.client.get("/holdings", "v3", params);
+  async getSectorWeighting({ symbol }) {
+    return this.client.get(`/etf-sector-weightings/${symbol}`, "v3");
+  }
+  /**
+   * Get ETF country weighting
+   * https://site.financialmodelingprep.com/developer/docs#etf-country-weighting-etf-holdings
+   * @param symbol - The symbol of the ETF to get the country weighting for
+   * @returns The FMP ETF Country Weighting endpoint provides a breakdown of the percentage of an ETF's assets that are invested in each country. For example, an investor may want to invest in an ETF that has a high exposure to China if they believe that the Chinese economy is poised for growth.
+   */
+  async getCountryWeighting({ symbol }) {
+    return this.client.get(`/etf-country-weightings/${symbol}`, "v3");
+  }
+  /**
+   * Get ETF Stock exposure
+   * https://site.financialmodelingprep.com/developer/docs#etf-sector-exposure-etf-holdings
+   * @param symbol - The symbol of the ETF to get the stock exposure for
+   * @returns This endpoint returns asset exposure from all ETFs that have it in their holdings. It has properties like market value, share number or weight percentage. It can be useful for looking up stock you like to check what ETF has it on their portfolio.
+   */
+  async getStockExposure({ symbol }) {
+    return this.client.get(`/etf-stock-exposure/${symbol}`, "v3");
   }
 };
 
@@ -449,6 +561,8 @@ var MutualFundEndpoints = class {
   }
   /**
    * Get mutual fund quote
+   * @param params - Parameters for the mutual fund quote request
+   * @returns Mutual fund quote data
    */
   async getQuote(params) {
     return this.client.get("/quote", "v3", params);
@@ -474,12 +588,18 @@ var BondEndpoints = class {
   }
   /**
    * Get bond quote
+   * @param params - Parameters for the bond quote request
+   * @returns Bond quote data
    */
   async getQuote(params) {
     return this.client.get("/quote", "v3", params);
   }
   /**
    * Get historical bond prices
+   * @param symbol - The bond symbol to get the historical prices for
+   * @param from - The start date to get the historical prices for
+   * @param to - The end date to get the historical prices for
+   * @returns Historical bond price data
    */
   async getHistoricalPrice({
     symbol,
@@ -549,33 +669,41 @@ var MarketEndpoints = class {
   }
   /**
    * Get top gainers
+   * https://site.financialmodelingprep.com/developer/docs#market-biggest-gainers-market-overview
+   * @returns The FMP Market Biggest Gainers endpoint provides a list of the stocks that have gained the most value on a given day. This information can be used by investors to identify stocks that are momentum and to potential investment opportunities.
    */
   async getGainers() {
-    return this.client.get("/gainers", "v3");
+    return this.client.get("/stock_market/gainers", "v3");
   }
   /**
    * Get top losers
+   * https://site.financialmodelingprep.com/developer/docs#market-biggest-losers-market-overview
+   * @returns The FMP Market Biggest Losers endpoint provides a list of the stocks that have lost the most value on a given day. This information can be used by investors to identify stocks that are underperforming and to potential trading opportunities.
    */
   async getLosers() {
-    return this.client.get("/losers", "v3");
+    return this.client.get("/stock_market/losers", "v3");
   }
   /**
    * Get most active stocks
    */
   async getMostActive() {
-    return this.client.get("/most-active", "v3");
+    return this.client.get("/stock_market/actives", "v3");
   }
   /**
    * Get sector performance
+   * https://site.financialmodelingprep.com/developer/docs#sector-performance-market-overview
+   * @returns The FMP Sector Performance endpoint provides the performance of each sector of the stock market over a specified period of time. This information can be used by investors to identify sectors that are outperforming or underperforming the market.
    */
   async getSectorPerformance() {
     return this.client.get("/sector-performance", "v3");
   }
   /**
    * Get market indices
+   * https://site.financialmodelingprep.com/developer/docs#market-index-market-overview
+   * @returns The FMP Market Index endpoint provides a list of all the major stock market indices, such as the S&P 500, the Dow Jones Industrial Average, and the Nasdaq Composite Index. This information can be used by investors to track the performance of the overall stock market and to identify sectors and industries that are outperforming or underperforming the market.
    */
-  async getMarketIndex(params = {}) {
-    return this.client.get("/market-index", "v3", params);
+  async getMarketIndex() {
+    return this.client.get("/quotes/index", "v3");
   }
 };
 
@@ -712,7 +840,7 @@ var CompanyEndpoints = class {
   async getCompanyProfile({
     symbol
   }) {
-    return this.client.get(`/profile/${symbol}`, "v3");
+    return this.client.getSingle(`/profile/${symbol}`, "v3");
   }
   /**
    * Get executive compensation
@@ -756,11 +884,9 @@ var CompanyEndpoints = class {
    * @param symbol - The stock symbol to get the shares float for
    * @returns The FMP Company Share Float endpoint provides the total number of shares that are publicly traded for a given company. This is also known as the company's float. The float is calculated by subtracting the number of restricted shares from the total number of outstanding shares.
    */
-  async getSharesFloat({
-    symbol
-  }) {
+  async getSharesFloat({ symbol }) {
     const params = { symbol };
-    return this.client.get(`/shares_float`, "v4", params);
+    return this.client.getSingle(`/shares_float`, "v4", params);
   }
   /**
    * Get historical shares float
@@ -788,7 +914,7 @@ var CompanyEndpoints = class {
     quarter
   }) {
     const params = { year, quarter };
-    return this.client.get(`/earning_call_transcript/${symbol}`, "v3", params);
+    return this.client.getSingle(`/earning_call_transcript/${symbol}`, "v3", params);
   }
 };
 
@@ -799,16 +925,16 @@ var FMP = class {
     const client = new FMPClient(config);
     this.stock = new StockEndpoints(client);
     this.financial = new FinancialEndpoints(client);
-    this.forex = new ForexEndpoints(client);
     this.crypto = new CryptoEndpoints(client);
     this.etf = new ETFEndpoints(client);
-    this.mutualFund = new MutualFundEndpoints(client);
-    this.bond = new BondEndpoints(client);
-    this.economic = new EconomicEndpoints(client);
     this.market = new MarketEndpoints(client);
     this.list = new ListEndpoints(client);
     this.calendar = new CalendarEndpoints(client);
     this.company = new CompanyEndpoints(client);
+    this.forex = new ForexEndpoints(client);
+    this.economic = new EconomicEndpoints(client);
+    this.bond = new BondEndpoints(client);
+    this.mutualFund = new MutualFundEndpoints(client);
   }
   /**
    * Get the underlying client instance for advanced usage