fmp-node-api 0.0.8 → 0.1.0

package/dist/index.mjs

@@ -14,29 +14,36 @@ function normalizeArrayResponse(data) {
 }
 function normalizeObjectResponse(data) {
   if (data == null) return {};
+  if (Array.isArray(data) && data.length === 0) return {};
   return data;
 }
 var FMPClient = class {
   constructor(config) {
+    if (!config.apiKey) {
+      throw new Error("API key is required for FMPClient");
+    }
     this.apiKey = config.apiKey;
-    this.v3Client = this.createClient("https://financialmodelingprep.com/api/v3", config.timeout);
-    this.v4Client = this.createClient("https://financialmodelingprep.com/api/v4", config.timeout);
-    this.stableClient = this.createClient(
-      "https://financialmodelingprep.com/stable",
-      config.timeout
-    );
-  }
-  createClient(baseURL, timeout) {
-    const client = axios.create({
-      baseURL,
-      timeout: timeout || 1e4,
+    this.v3Client = axios.create({
+      baseURL: "https://financialmodelingprep.com/api/v3",
+      timeout: config.timeout || 1e4,
+      headers: { "Content-Type": "application/json" }
+    });
+    this.v4Client = axios.create({
+      baseURL: "https://financialmodelingprep.com/api/v4",
+      timeout: config.timeout || 1e4,
+      headers: { "Content-Type": "application/json" }
+    });
+    this.stableClient = axios.create({
+      baseURL: "https://financialmodelingprep.com/stable",
+      timeout: config.timeout || 1e4,
       headers: { "Content-Type": "application/json" }
     });
-    client.interceptors.request.use((config) => {
-      config.params = { ...config.params, apikey: this.apiKey };
-      return config;
+    [this.v3Client, this.v4Client, this.stableClient].forEach((client) => {
+      client.interceptors.request.use((config2) => {
+        config2.params = { ...config2.params, apikey: this.apiKey };
+        return config2;
+      });
     });
-    return client;
   }
   /**
    * Standard get method - returns raw API response
@@ -106,137 +113,310 @@ var FMPClient = class {
   }
 };
 
-// src/shared.ts
-var FMPError = class extends Error {
-  constructor(message, status, code) {
-    super(message);
-    this.status = status;
-    this.code = code;
-    this.name = "FMPError";
-  }
-};
-
 // src/utils/validation.ts
-function validateApiKey(apiKey) {
-  if (!apiKey || typeof apiKey !== "string" || apiKey.trim().length === 0) {
-    throw new FMPError("API key is required and must be a non-empty string");
+var FMPValidation = class {
+  /**
+   * Validate stock symbol format
+   * @param symbol - The symbol to validate
+   * @returns True if the symbol format is valid
+   */
+  static isValidSymbol(symbol) {
+    if (!symbol || typeof symbol !== "string") {
+      return false;
+    }
+    return /^[A-Z]{1,5}$/.test(symbol);
   }
-}
-function validateSymbol(symbol) {
-  if (!symbol || typeof symbol !== "string" || symbol.trim().length === 0) {
-    throw new FMPError("Symbol is required and must be a non-empty string");
-  }
-  const symbolRegex = /^[A-Z0-9.-]+$/;
-  if (!symbolRegex.test(symbol.toUpperCase())) {
-    throw new FMPError(
-      "Invalid symbol format. Symbols should contain only letters, numbers, dots, and hyphens"
-    );
+  /**
+   * Validate crypto symbol format
+   * @param symbol - The crypto symbol to validate
+   * @returns True if the crypto symbol format is valid
+   */
+  static isValidCryptoSymbol(symbol) {
+    if (!symbol || typeof symbol !== "string") {
+      return false;
+    }
+    return /^[A-Z]{2,10}(USD|EUR|GBP|JPY|CAD|AUD|CHF|CNY)$/.test(symbol);
   }
-}
-function validateDate(date) {
-  if (!date || typeof date !== "string") {
-    throw new FMPError("Date is required and must be a string");
+  /**
+   * Validate forex pair format
+   * @param symbol - The forex pair to validate
+   * @returns True if the forex pair format is valid
+   */
+  static isValidForexPair(symbol) {
+    if (!symbol || typeof symbol !== "string") {
+      return false;
+    }
+    return /^[A-Z]{3}[A-Z]{3}$/.test(symbol);
   }
-  const dateRegex = /^\d{4}-\d{2}-\d{2}$/;
-  if (!dateRegex.test(date)) {
-    throw new FMPError("Invalid date format. Use YYYY-MM-DD format");
+  /**
+   * Validate date format (YYYY-MM-DD)
+   * @param date - The date string to validate
+   * @returns True if the date format is valid
+   */
+  static isValidDate(date) {
+    if (!date || typeof date !== "string") {
+      return false;
+    }
+    const dateRegex = /^\d{4}-\d{2}-\d{2}$/;
+    if (!dateRegex.test(date)) {
+      return false;
+    }
+    const dateObj = new Date(date);
+    return !isNaN(dateObj.getTime()) && dateObj.toISOString().split("T")[0] === date;
   }
-  const parsedDate = new Date(date);
-  if (isNaN(parsedDate.getTime())) {
-    throw new FMPError("Invalid date");
+  /**
+   * Validate date range
+   * @param from - Start date
+   * @param to - End date
+   * @returns True if the date range is valid
+   */
+  static isValidDateRange(from, to) {
+    if (!this.isValidDate(from) || !this.isValidDate(to)) {
+      return false;
+    }
+    const fromDate = new Date(from);
+    const toDate = new Date(to);
+    return fromDate <= toDate;
   }
-}
-function validatePeriod(period) {
-  if (period && !["annual", "quarter"].includes(period)) {
-    throw new FMPError('Period must be either "annual" or "quarter"');
+  /**
+   * Validate API response structure
+   * @param response - The response to validate
+   * @returns True if the response has the expected structure
+   */
+  static isValidResponse(response) {
+    return Boolean(
+      response && typeof response === "object" && typeof response.success === "boolean"
+    );
   }
-}
-function validateLimit(limit) {
-  if (limit !== void 0 && (typeof limit !== "number" || limit < 1 || limit > 1e3)) {
-    throw new FMPError("Limit must be a number between 1 and 1000");
+  /**
+   * Validate API key format
+   * @param apiKey - The API key to validate
+   * @returns True if the API key format is valid
+   */
+  static isValidApiKey(apiKey) {
+    if (!apiKey || typeof apiKey !== "string") {
+      return false;
+    }
+    return /^[a-zA-Z0-9]{32,}$/.test(apiKey);
   }
-}
-function validatePage(page) {
-  if (page !== void 0 && (typeof page !== "number" || page < 0)) {
-    throw new FMPError("Page must be a non-negative number");
+  /**
+   * Validate period parameter
+   * @param period - The period to validate
+   * @returns True if the period is valid
+   */
+  static isValidPeriod(period) {
+    if (!period || typeof period !== "string") {
+      return false;
+    }
+    return ["annual", "quarter", "fy"].includes(period.toLowerCase());
   }
-}
-
-// src/endpoints/stock.ts
-var StockEndpoints = class {
-  constructor(client) {
-    this.client = client;
+  /**
+   * Validate limit parameter
+   * @param limit - The limit to validate
+   * @returns True if the limit is valid
+   */
+  static isValidLimit(limit) {
+    return typeof limit === "number" && Number.isInteger(limit) && limit > 0 && limit <= 1e3;
   }
   /**
-   * Get real-time stock quote
-   * @deprecated Use `fmp.quote.getQuote()` instead. This method will be removed in version 0.1.0.
-   * @param symbol - The stock symbol to get the quote for
-   * @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.
+   * Get validation errors for quote parameters
+   * @param params - The parameters to validate
+   * @returns Array of validation error messages
    */
-  async getQuote({ symbol }) {
-    console.warn(
-      "\u26A0\uFE0F  StockEndpoints.getQuote() is deprecated. Use fmp.quote.getQuote() instead. This method will be removed in version 0.1.0."
-    );
-    return this.client.getSingle(`/quote/${symbol}`, "v3");
+  static validateQuoteParams(params) {
+    const errors = [];
+    if (!params) {
+      errors.push("Parameters object is required");
+      return errors;
+    }
+    if (!params.symbol) {
+      errors.push("Symbol is required");
+    } else if (!this.isValidSymbol(params.symbol) && !this.isValidCryptoSymbol(params.symbol) && !this.isValidForexPair(params.symbol)) {
+      errors.push("Invalid symbol format");
+    }
+    if (params.from && !this.isValidDate(params.from)) {
+      errors.push("Invalid from date format (expected YYYY-MM-DD)");
+    }
+    if (params.to && !this.isValidDate(params.to)) {
+      errors.push("Invalid to date format (expected YYYY-MM-DD)");
+    }
+    if (params.from && params.to && !this.isValidDateRange(params.from, params.to)) {
+      errors.push("From date must be before or equal to to date");
+    }
+    return errors;
   }
   /**
-   * Get historical stock prices
-   * @deprecated Use `fmp.quote.getHistoricalPrice()` instead. This method will be removed in version 0.1.0.
-   * @param symbol - The stock 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 The FMP Daily Chart endpoint provides daily stock data for a specified company, including opening, high, low, and closing prices, with a default limit of 5 years of historical data. To access data beyond this limit, use the from and to parameters for custom date ranges, each with a 5-year limit
+   * Get validation errors for financial statement parameters
+   * @param params - The parameters to validate
+   * @returns Array of validation error messages
    */
-  async getHistoricalPrice({
-    symbol,
-    from,
-    to
-  }) {
-    console.warn(
-      "\u26A0\uFE0F  StockEndpoints.getHistoricalPrice() is deprecated. Use fmp.quote.getHistoricalPrice() instead. This method will be removed in version 0.1.0."
-    );
-    const params = {};
-    if (from) params.from = from;
-    if (to) params.to = to;
-    return this.client.getSingle(`/historical-price-full/${symbol}`, "v3", params);
+  static validateFinancialParams(params) {
+    const errors = [];
+    if (!params) {
+      errors.push("Parameters object is required");
+      return errors;
+    }
+    if (!params.symbol) {
+      errors.push("Symbol is required");
+    } else if (!this.isValidSymbol(params.symbol)) {
+      errors.push("Invalid symbol format");
+    }
+    if (params.period && !this.isValidPeriod(params.period)) {
+      errors.push('Invalid period (must be "annual", "quarter", or "FY")');
+    }
+    if (params.limit && !this.isValidLimit(params.limit)) {
+      errors.push("Invalid limit (must be a positive integer <= 1000)");
+    }
+    return errors;
+  }
+  /**
+   * Get validation errors for date range parameters
+   * @param params - The parameters to validate
+   * @returns Array of validation error messages
+   */
+  static validateDateRangeParams(params) {
+    const errors = [];
+    if (!params) {
+      errors.push("Parameters object is required");
+      return errors;
+    }
+    if (params.from && !this.isValidDate(params.from)) {
+      errors.push("Invalid from date format (expected YYYY-MM-DD)");
+    }
+    if (params.to && !this.isValidDate(params.to)) {
+      errors.push("Invalid to date format (expected YYYY-MM-DD)");
+    }
+    if (params.from && params.to && !this.isValidDateRange(params.from, params.to)) {
+      errors.push("From date must be before or equal to to date");
+    }
+    return errors;
+  }
+  /**
+   * Validate and throw error if validation fails
+   * @param errors - Array of validation errors
+   * @param context - Context for the error message
+   */
+  static throwIfInvalid(errors, context = "Validation") {
+    if (errors.length > 0) {
+      throw new Error(`${context} failed: ${errors.join(", ")}`);
+    }
+  }
+};
+
+// src/endpoints/stock.ts
+var StockEndpoints = class {
+  constructor(client) {
+    this.client = client;
   }
   /**
-   * Get market cap
-   * https://site.financialmodelingprep.com/developer/docs#market-cap-company-information
-   * @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.
+   * Get current market capitalization for a stock
+   *
+   * Market capitalization represents the total value of a company's outstanding shares.
+   * Calculated by multiplying the current share price by the number of outstanding shares.
+   * This metric is crucial for understanding a company's size and market position.
+   *
+   * @param symbol - The stock symbol to get market cap for (e.g., 'AAPL', 'MSFT', 'GOOGL')
+   *
+   * @returns Promise resolving to market cap data including symbol, date, and market cap value
+   *
+   * @example
+   * ```typescript
+   * // Get market cap for Apple
+   * const marketCap = await fmp.stock.getMarketCap('AAPL');
+   * console.log(`Apple's market cap: $${marketCap.data.marketCap.toLocaleString()}`);
+   *
+   * // Get market cap for Microsoft
+   * const msftCap = await fmp.stock.getMarketCap('MSFT');
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#market-cap-company-information|FMP Market Cap Documentation}
    */
-  async getMarketCap({ symbol }) {
+  async getMarketCap(symbol) {
     return this.client.getSingle(`/market-capitalization/${symbol}`, "v3");
   }
   /**
-   * Get stock splits
-   * https://site.financialmodelingprep.com/developer/docs#splits-historical-splits
-   * @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.
+   * Get historical stock splits for a company
+   *
+   * Stock splits occur when a company increases the number of shares by dividing existing shares.
+   * This endpoint provides the complete history of stock splits including dates, ratios, and split types.
+   * Useful for adjusting historical price data and understanding corporate actions.
+   *
+   * @param symbol - The stock symbol to get split history for (e.g., 'AAPL', 'TSLA', 'NVDA')
+   *
+   * @returns Promise resolving to historical stock splits with dates, labels, and split ratios
+   *
+   * @example
+   * ```typescript
+   * // Get Apple's split history
+   * const splits = await fmp.stock.getStockSplits('AAPL');
+   * splits.data.historical.forEach(split => {
+   *   console.log(`${split.date}: ${split.numerator}:${split.denominator} split`);
+   * });
+   *
+   * // Get Tesla's split history
+   * const teslaSplits = await fmp.stock.getStockSplits('TSLA');
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#splits-historical-splits|FMP Stock Splits Documentation}
    */
-  async getStockSplits({ symbol }) {
+  async getStockSplits(symbol) {
     return this.client.get(`/historical-price-full/stock_split/${symbol}`, "v3");
   }
   /**
-   * Get dividend history
-   * https://site.financialmodelingprep.com/developer/docs#dividends-historical-dividends
-   * @param symbol - The stock symbol to get the dividend history for
-   * @returns A list of historical dividend payments for publicly traded companies, including the date of the dividend payment, the ex-dividend date, and the dividend per share.
+   * Get historical dividend payments for a stock
+   *
+   * Dividends are periodic payments made by companies to shareholders from profits.
+   * This endpoint provides the complete dividend history including payment dates, amounts,
+   * and important dates like ex-dividend, record, and declaration dates.
+   *
+   * @param symbol - The stock symbol to get dividend history for (e.g., 'KO', 'JNJ', 'PG')
+   *
+   * @returns Promise resolving to dividend history with payment details and important dates
+   *
+   * @example
+   * ```typescript
+   * // Get Coca-Cola's dividend history
+   * const dividends = await fmp.stock.getDividendHistory('KO');
+   * dividends.data.historical.forEach(dividend => {
+   *   console.log(`${dividend.date}: $${dividend.dividend} per share`);
+   * });
+   *
+   * // Get Johnson & Johnson's dividend history
+   * const jnjDividends = await fmp.stock.getDividendHistory('JNJ');
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#dividends-historical-dividends|FMP Dividends Documentation}
    */
-  async getDividendHistory({
-    symbol
-  }) {
+  async getDividendHistory(symbol) {
     return this.client.getSingle(`/historical-price-full/stock_dividend/${symbol}`, "v3");
   }
   /**
-   * Get stock real time price
-   * @param symbol - The stock symbol to get the real time price for
-   * @returns The real time price for the stock
+   * Get real-time stock prices for multiple symbols
+   *
+   * Provides current market prices for stocks with minimal data overhead.
+   * Returns basic price information including symbol and current price.
+   * Ideal for quick price checks and portfolio monitoring.
+   *
+   * @param symbols - Array of stock symbols to get real-time prices for
+   *
+   * @returns Promise resolving to array of real-time price data with symbol and price
+   *
+   * @example
+   * ```typescript
+   * // Get prices for multiple tech stocks
+   * const prices = await fmp.stock.getRealTimePrice([
+   *   'AAPL', 'MSFT', 'GOOGL', 'AMZN', 'TSLA'
+   * ]);
+   *
+   * prices.data.forEach(stock => {
+   *   console.log(`${stock.symbol}: $${stock.price}`);
+   * });
+   *
+   * // Get price for single stock
+   * const aaplPrice = await fmp.stock.getRealTimePrice(['AAPL']);
+   * ```
    */
-  async getRealTimePrice({
-    symbols
-  }) {
+  async getRealTimePrice(symbols) {
     const url = `stock/real-time-price/${symbols.join(",")}`;
     const result = await this.client.get(url, "v3");
     if (result.success && result.data && !Array.isArray(result.data)) {
@@ -265,14 +445,38 @@ var StockEndpoints = class {
     return { ...result, data: filteredData };
   }
   /**
-   * Get stock real time price full
-   * https://site.financialmodelingprep.com/developer/docs#real-time-full-price-quote
-   * @param symbols - The stock symbols to get the real time price for
-   * @returns The real time price for the stocks
+   * Get comprehensive real-time stock data for multiple symbols
+   *
+   * Provides detailed real-time market data including bid/ask prices, volume, trade sizes,
+   * and timestamps. This endpoint offers much more information than the basic real-time price.
+   * Perfect for trading applications, market analysis, and detailed price monitoring.
+   *
+   * @param symbols - Array of stock symbols to get detailed real-time data for
+   *
+   * @returns Promise resolving to array of detailed real-time data including bid/ask, volume, and timestamps
+   *
+   * @example
+   * ```typescript
+   * // Get detailed data for multiple stocks
+   * const detailedData = await fmp.stock.getRealTimePriceForMultipleStocks([
+   *   'AAPL', 'MSFT', 'GOOGL'
+   * ]);
+   *
+   * detailedData.data.forEach(stock => {
+   *   console.log(`${stock.symbol}:`);
+   *   console.log(`  Bid: $${stock.bidPrice} (${stock.bidSize} shares)`);
+   *   console.log(`  Ask: $${stock.askPrice} (${stock.askSize} shares)`);
+   *   console.log(`  Last: $${stock.lastSalePrice} (${stock.lastSaleSize} shares)`);
+   *   console.log(`  Volume: ${stock.volume.toLocaleString()}`);
+   * });
+   *
+   * // Get detailed data for single stock
+   * const aaplDetailed = await fmp.stock.getRealTimePriceForMultipleStocks(['AAPL']);
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#real-time-full-price-quote|FMP Real-Time Full Price Documentation}
    */
-  async getRealTimePriceForMultipleStocks({
-    symbols
-  }) {
+  async getRealTimePriceForMultipleStocks(symbols) {
     const url = `stock/full/real-time-price/${symbols.join(",")}`;
     const result = await this.client.get(url, "v3");
     if (result.success && result.data && !Array.isArray(result.data)) {
@@ -310,391 +514,643 @@ var FinancialEndpoints = class {
     this.client = client;
   }
   /**
-   * Get income statement
-   * https://site.financialmodelingprep.com/developer/docs#income-statements-financial-statements
-   * @param symbol - The stock symbol to get the income statement for
-   * @param period - The period to get the income statement for (annual or quarter)
-   * @param limit - The number of periods to get
-   * @returns FMP's Income Statement API provides access to real-time income statement data for a wide range of companies, including public companies, private companies, and ETFs. This data can be used to track a company's profitability over time, to compare a company to its competitors, and to identify trends in a company's business.
+   * Get income statement data
+   *
+   * Provides comprehensive income statement data including revenue, expenses,
+   * net income, and earnings per share. Essential for analyzing company
+   * profitability, revenue trends, and financial performance over time.
+   *
+   * @param params - Income statement request parameters
+   * @param params.symbol - The stock symbol to get income statement for (e.g., 'AAPL', 'MSFT', 'GOOGL')
+   * @param params.period - The reporting period: 'annual' or 'quarter' (default: 'annual')
+   * @param params.limit - Number of periods to retrieve (default: 5)
+   *
+   * @returns Promise resolving to array of income statement data with financial metrics
+   *
+   * @example
+   * ```typescript
+   * // Get annual income statements for Apple
+   * const incomeStatements = await fmp.financial.getIncomeStatement({ symbol: 'AAPL' });
+   * incomeStatements.data.forEach(statement => {
+   *   console.log(`${statement.date}: Revenue $${statement.revenue.toLocaleString()}, Net Income $${statement.netIncome.toLocaleString()}`);
+   * });
+   *
+   * // Get quarterly income statements for Microsoft
+   * const quarterlyIncome = await fmp.financial.getIncomeStatement({ symbol: 'MSFT', period: 'quarter', limit: 8 });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#income-statements-financial-statements|FMP Income Statement Documentation}
    */
-  async getIncomeStatement({
-    symbol,
-    period = "annual",
-    limit = 5
-  }) {
+  async getIncomeStatement(params) {
+    const { symbol, period = "annual", limit = 5 } = params;
     return this.client.get(`/income-statement/${symbol}?period=${period}&limit=${limit}`, "v3");
   }
   /**
-   * Get balance sheet
-   * https://site.financialmodelingprep.com/developer/docs#balance-sheet-statements-financial-statements
-   * @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.
+   * Get balance sheet data
+   *
+   * Provides comprehensive balance sheet data including assets, liabilities,
+   * and shareholder equity. Essential for analyzing company financial position,
+   * liquidity, and capital structure.
+   *
+   * @param params - Balance sheet request parameters
+   * @param params.symbol - The stock symbol to get balance sheet for (e.g., 'AAPL', 'MSFT', 'GOOGL')
+   * @param params.period - The reporting period: 'annual' or 'quarter' (default: 'annual')
+   * @param params.limit - Number of periods to retrieve (default: 5)
+   *
+   * @returns Promise resolving to array of balance sheet data with financial position metrics
+   *
+   * @example
+   * ```typescript
+   * // Get annual balance sheets for Apple
+   * const balanceSheets = await fmp.financial.getBalanceSheet({ symbol: 'AAPL' });
+   * balanceSheets.data.forEach(sheet => {
+   *   console.log(`${sheet.date}: Assets $${sheet.totalAssets.toLocaleString()}, Equity $${sheet.totalStockholdersEquity.toLocaleString()}`);
+   * });
+   *
+   * // Get quarterly balance sheets for Microsoft
+   * const quarterlyBalance = await fmp.financial.getBalanceSheet({ symbol: 'MSFT', period: 'quarter', limit: 8 });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#balance-sheet-statements-financial-statements|FMP Balance Sheet Documentation}
    */
-  async getBalanceSheet({
-    symbol,
-    period = "annual",
-    limit = 5
-  }) {
+  async getBalanceSheet(params) {
+    const { symbol, period = "annual", limit = 5 } = params;
     return this.client.get(
       `/balance-sheet-statement/${symbol}?period=${period}&limit=${limit}`,
       "v3"
     );
   }
   /**
-   * Get cash flow statement
-   * https://site.financialmodelingprep.com/developer/docs#cashflow-statements-financial-statements
-   * @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.
+   * Get cash flow statement data
+   *
+   * Provides comprehensive cash flow data including operating, investing,
+   * and financing cash flows. Essential for analyzing company cash generation,
+   * capital allocation, and financial sustainability.
+   *
+   * @param params - Cash flow statement request parameters
+   * @param params.symbol - The stock symbol to get cash flow statement for (e.g., 'AAPL', 'MSFT', 'GOOGL')
+   * @param params.period - The reporting period: 'annual' or 'quarter' (default: 'annual')
+   * @param params.limit - Number of periods to retrieve (default: 5)
+   *
+   * @returns Promise resolving to array of cash flow statement data with cash flow metrics
+   *
+   * @example
+   * ```typescript
+   * // Get annual cash flow statements for Apple
+   * const cashFlows = await fmp.financial.getCashFlowStatement({ symbol: 'AAPL' });
+   * cashFlows.data.forEach(flow => {
+   *   console.log(`${flow.date}: Operating CF $${flow.operatingCashFlow.toLocaleString()}, Free CF $${flow.freeCashFlow.toLocaleString()}`);
+   * });
+   *
+   * // Get quarterly cash flow statements for Microsoft
+   * const quarterlyCashFlow = await fmp.financial.getCashFlowStatement({ symbol: 'MSFT', period: 'quarter', limit: 8 });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#cashflow-statements-financial-statements|FMP Cash Flow Statement Documentation}
    */
-  async getCashFlowStatement({
-    symbol,
-    period = "annual",
-    limit = 5
-  }) {
+  async getCashFlowStatement(params) {
+    const { symbol, period = "annual", limit = 5 } = params;
     return this.client.get(`/cash-flow-statement/${symbol}?period=${period}&limit=${limit}`, "v3");
   }
   /**
-   * Get key metrics
-   * https://site.financialmodelingprep.com/developer/docs#key-metrics-statement-analysis
-   * @param symbol - The stock symbol to get the key metrics for
-   * @param period - The period to get the key metrics for (annual or quarter)
-   * @param limit - The number of periods to get
-   * @returns Get key financial metrics for a company, including revenue, net income, and price-to-earnings ratio (P/E ratio). Assess a company's financial performance and compare it to its competitors.
+   * Get key financial metrics
+   *
+   * Provides essential financial metrics including revenue, net income,
+   * P/E ratio, and other key performance indicators. Essential for
+   * fundamental analysis and company valuation.
+   *
+   * @param params - Key metrics request parameters
+   * @param params.symbol - The stock symbol to get key metrics for (e.g., 'AAPL', 'MSFT', 'GOOGL')
+   * @param params.period - The reporting period: 'annual' or 'quarter' (default: 'annual')
+   * @param params.limit - Number of periods to retrieve (default: 5)
+   *
+   * @returns Promise resolving to array of key metrics data with financial indicators
+   *
+   * @example
+   * ```typescript
+   * // Get key metrics for Apple
+   * const keyMetrics = await fmp.financial.getKeyMetrics({ symbol: 'AAPL' });
+   * keyMetrics.data.forEach(metric => {
+   *   console.log(`${metric.date}: P/E ${metric.peRatio}, ROE ${metric.roe}%`);
+   * });
+   *
+   * // Get quarterly key metrics for Microsoft
+   * const quarterlyMetrics = await fmp.financial.getKeyMetrics({ symbol: 'MSFT', period: 'quarter', limit: 8 });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#key-metrics-statement-analysis|FMP Key Metrics Documentation}
    */
-  async getKeyMetrics({
-    symbol,
-    period = "annual",
-    limit = 5
-  }) {
+  async getKeyMetrics(params) {
+    const { symbol, period = "annual", limit = 5 } = params;
     return this.client.get(`/key-metrics/${symbol}?period=${period}&limit=${limit}`, "v3");
   }
   /**
    * Get financial ratios
-   * https://site.financialmodelingprep.com/developer/docs#ratios-statement-analysis
-   * @param symbol - The stock symbol to get the financial ratios for
-   * @param period - The period to get the financial ratios for (annual or quarter)
-   * @param limit - The number of periods to get
-   * @returns Get financial ratios for a company, such as the P/B ratio and the ROE. Assess a company's financial health and compare it to its competitors.
+   *
+   * Provides comprehensive financial ratios including P/B ratio, ROE,
+   * debt-to-equity, and other important ratios. Essential for analyzing
+   * company financial health and comparing with peers.
+   *
+   * @param params - Financial ratios request parameters
+   * @param params.symbol - The stock symbol to get financial ratios for (e.g., 'AAPL', 'MSFT', 'GOOGL')
+   * @param params.period - The reporting period: 'annual' or 'quarter' (default: 'annual')
+   * @param params.limit - Number of periods to retrieve (default: 5)
+   *
+   * @returns Promise resolving to array of financial ratios data with ratio metrics
+   *
+   * @example
+   * ```typescript
+   * // Get financial ratios for Apple
+   * const ratios = await fmp.financial.getFinancialRatios({ symbol: 'AAPL' });
+   * ratios.data.forEach(ratio => {
+   *   console.log(`${ratio.date}: P/B ${ratio.priceToBookRatio}, Debt/Equity ${ratio.debtToEquity}`);
+   * });
+   *
+   * // Get quarterly ratios for Microsoft
+   * const quarterlyRatios = await fmp.financial.getFinancialRatios({ symbol: 'MSFT', period: 'quarter', limit: 8 });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#ratios-statement-analysis|FMP Financial Ratios Documentation}
    */
-  async getFinancialRatios({
-    symbol,
-    period = "annual",
-    limit = 5
-  }) {
+  async getFinancialRatios(params) {
+    const { symbol, period = "annual", limit = 5 } = params;
     return this.client.get(`/ratios/${symbol}?period=${period}&limit=${limit}`, "v3");
   }
   /**
-   * Get enterprise value
-   * https://site.financialmodelingprep.com/developer/docs#enterprise-values-statement-analysis
-   * @param symbol - The stock symbol to get the enterprise value for
-   * @param period - The period to get the enterprise value for (annual or quarter)
-   * @param limit - The number of periods to get
-   * @returns Get the enterprise value of a company, which is the total value of a company, including its equity and debt. Assess a company's overall value and compare it to its peers.
+   * Get enterprise value data
+   *
+   * Provides enterprise value metrics including total enterprise value,
+   * market cap, and debt information. Essential for company valuation
+   * and comparing companies with different capital structures.
+   *
+   * @param params - Enterprise value request parameters
+   * @param params.symbol - The stock symbol to get enterprise value for (e.g., 'AAPL', 'MSFT', 'GOOGL')
+   * @param params.period - The reporting period: 'annual' or 'quarter' (default: 'annual')
+   * @param params.limit - Number of periods to retrieve (default: 5)
+   *
+   * @returns Promise resolving to array of enterprise value data with valuation metrics
+   *
+   * @example
+   * ```typescript
+   * // Get enterprise value for Apple
+   * const enterpriseValue = await fmp.financial.getEnterpriseValue({ symbol: 'AAPL' });
+   * enterpriseValue.data.forEach(ev => {
+   *   console.log(`${ev.date}: EV $${ev.enterpriseValue.toLocaleString()}, Market Cap $${ev.marketCapitalization.toLocaleString()}`);
+   * });
+   *
+   * // Get quarterly enterprise value for Microsoft
+   * const quarterlyEV = await fmp.financial.getEnterpriseValue({ symbol: 'MSFT', period: 'quarter', limit: 8 });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#enterprise-values-statement-analysis|FMP Enterprise Value Documentation}
    */
-  async getEnterpriseValue({
-    symbol,
-    period = "annual",
-    limit = 5
-  }) {
+  async getEnterpriseValue(params) {
+    const { symbol, period = "annual", limit = 5 } = params;
     return this.client.get(`/enterprise-value/${symbol}?period=${period}&limit=${limit}`, "v3");
   }
   /**
-   * Get cashflow growth
-   * https://site.financialmodelingprep.com/developer/docs#cashflow-growth-statement-analysis
-   * @param symbol - The stock symbol to get the cashflow growth for
-   * @param period - The period to get the cashflow growth for (annual or quarter)
-   * @param limit - The number of periods to get
-   * @returns Get the cash flow growth rate for a company. Measure how quickly a company's cash flow is growing.
+   * Get cash flow growth data
+   *
+   * Provides cash flow growth rates showing how quickly a company's
+   * cash flows are growing over time. Essential for analyzing cash
+   * generation trends and financial sustainability.
+   *
+   * @param params - Cash flow growth request parameters
+   * @param params.symbol - The stock symbol to get cash flow growth for (e.g., 'AAPL', 'MSFT', 'GOOGL')
+   * @param params.period - The reporting period: 'annual' or 'quarter' (default: 'annual')
+   * @param params.limit - Number of periods to retrieve (default: 5)
+   *
+   * @returns Promise resolving to array of cash flow growth data with growth metrics
+   *
+   * @example
+   * ```typescript
+   * // Get cash flow growth for Apple
+   * const cashFlowGrowth = await fmp.financial.getCashflowGrowth({ symbol: 'AAPL' });
+   * cashFlowGrowth.data.forEach(growth => {
+   *   console.log(`${growth.date}: Operating CF Growth ${growth.operatingCashFlowGrowth}%`);
+   * });
+   *
+   * // Get quarterly cash flow growth for Microsoft
+   * const quarterlyGrowth = await fmp.financial.getCashflowGrowth({ symbol: 'MSFT', period: 'quarter', limit: 8 });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#cashflow-growth-statement-analysis|FMP Cash Flow Growth Documentation}
    */
-  async getCashflowGrowth({
-    symbol,
-    period = "annual",
-    limit = 5
-  }) {
+  async getCashflowGrowth(params) {
+    const { symbol, period = "annual", limit = 5 } = params;
     return this.client.get(
       `/cash-flow-statement-growth/${symbol}?period=${period}&limit=${limit}`,
       "v3"
     );
   }
   /**
-   *  Get income growth
-   * https://site.financialmodelingprep.com/developer/docs#income-growth-statement-analysis
-   * @param symbol - The stock symbol to get the income growth for
-   * @param period - The period to get the income growth for (annual or quarter)
-   * @param limit - The number of periods to get
-   * @returns Get the income growth rate for a company. Measure how quickly a company's income is growing.
+   * Get income growth data
+   *
+   * Provides income growth rates showing how quickly a company's
+   * revenue and net income are growing over time. Essential for
+   * analyzing profitability trends and business momentum.
+   *
+   * @param params - Income growth request parameters
+   * @param params.symbol - The stock symbol to get income growth for (e.g., 'AAPL', 'MSFT', 'GOOGL')
+   * @param params.period - The reporting period: 'annual' or 'quarter' (default: 'annual')
+   * @param params.limit - Number of periods to retrieve (default: 5)
+   *
+   * @returns Promise resolving to array of income growth data with growth metrics
+   *
+   * @example
+   * ```typescript
+   * // Get income growth for Apple
+   * const incomeGrowth = await fmp.financial.getIncomeGrowth({ symbol: 'AAPL' });
+   * incomeGrowth.data.forEach(growth => {
+   *   console.log(`${growth.date}: Revenue Growth ${growth.revenueGrowth}%, Net Income Growth ${growth.netIncomeGrowth}%`);
+   * });
+   *
+   * // Get quarterly income growth for Microsoft
+   * const quarterlyGrowth = await fmp.financial.getIncomeGrowth({ symbol: 'MSFT', period: 'quarter', limit: 8 });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#income-growth-statement-analysis|FMP Income Growth Documentation}
    */
-  async getIncomeGrowth({
-    symbol,
-    period = "annual",
-    limit = 5
-  }) {
+  async getIncomeGrowth(params) {
+    const { symbol, period = "annual", limit = 5 } = params;
     return this.client.get(
       `/income-statement-growth/${symbol}?period=${period}&limit=${limit}`,
       "v3"
     );
   }
   /**
-   * Get balance sheet growth
-   * https://site.financialmodelingprep.com/developer/docs#balance-sheet-growth-statement-analysis
-   * @param symbol - The stock symbol to get the balance sheet growth for
-   * @param period - The period to get the balance sheet growth for (annual or quarter)
-   * @param limit - The number of periods to get
-   * @returns Get the balance sheet growth rate for a company. Measure how quickly a company's assets and liabilities are growing.
+   * Get balance sheet growth data
+   *
+   * Provides balance sheet growth rates showing how quickly a company's
+   * assets, liabilities, and equity are growing over time. Essential for
+   * analyzing capital structure trends and financial position changes.
+   *
+   * @param params - Balance sheet growth request parameters
+   * @param params.symbol - The stock symbol to get balance sheet growth for (e.g., 'AAPL', 'MSFT', 'GOOGL')
+   * @param params.period - The reporting period: 'annual' or 'quarter' (default: 'annual')
+   * @param params.limit - Number of periods to retrieve (default: 5)
+   *
+   * @returns Promise resolving to array of balance sheet growth data with growth metrics
+   *
+   * @example
+   * ```typescript
+   * // Get balance sheet growth for Apple
+   * const balanceSheetGrowth = await fmp.financial.getBalanceSheetGrowth({ symbol: 'AAPL' });
+   * balanceSheetGrowth.data.forEach(growth => {
+   *   console.log(`${growth.date}: Assets Growth ${growth.totalAssetsGrowth}%, Equity Growth ${growth.totalStockholdersEquityGrowth}%`);
+   * });
+   *
+   * // Get quarterly balance sheet growth for Microsoft
+   * const quarterlyGrowth = await fmp.financial.getBalanceSheetGrowth({ symbol: 'MSFT', period: 'quarter', limit: 8 });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#balance-sheet-growth-statement-analysis|FMP Balance Sheet Growth Documentation}
    */
-  async getBalanceSheetGrowth({
-    symbol,
-    period = "annual",
-    limit = 5
-  }) {
+  async getBalanceSheetGrowth(params) {
+    const { symbol, period = "annual", limit = 5 } = params;
     return this.client.get(
       `/balance-sheet-statement-growth/${symbol}?period=${period}&limit=${limit}`,
       "v3"
     );
   }
   /**
-   * Get financial growth
-   * https://site.financialmodelingprep.com/developer/docs#financial-growth-statement-analysis
-   * @param symbol - The stock symbol to get the financial growth for
-   * @param period - The period to get the financial growth for (annual or quarter)
-   * @param limit - The number of periods to get
-   * @returns Financial Growth Get the financial growth rate for a company. Measure how quickly a company's overall financial performance is improving.
+   * Get financial growth data
+   *
+   * Provides comprehensive financial growth rates across all key
+   * financial metrics. Essential for analyzing overall financial
+   * performance trends and business momentum.
+   *
+   * @param params - Financial growth request parameters
+   * @param params.symbol - The stock symbol to get financial growth for (e.g., 'AAPL', 'MSFT', 'GOOGL')
+   * @param params.period - The reporting period: 'annual' or 'quarter' (default: 'annual')
+   * @param params.limit - Number of periods to retrieve (default: 5)
+   *
+   * @returns Promise resolving to array of financial growth data with comprehensive growth metrics
+   *
+   * @example
+   * ```typescript
+   * // Get financial growth for Apple
+   * const financialGrowth = await fmp.financial.getFinancialGrowth({ symbol: 'AAPL' });
+   * financialGrowth.data.forEach(growth => {
+   *   console.log(`${growth.date}: Revenue Growth ${growth.revenueGrowth}%, EPS Growth ${growth.epsGrowth}%`);
+   * });
+   *
+   * // Get quarterly financial growth for Microsoft
+   * const quarterlyGrowth = await fmp.financial.getFinancialGrowth({ symbol: 'MSFT', period: 'quarter', limit: 8 });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#financial-growth-statement-analysis|FMP Financial Growth Documentation}
    */
-  async getFinancialGrowth({
-    symbol,
-    period = "annual",
-    limit = 5
-  }) {
+  async getFinancialGrowth(params) {
+    const { symbol, period = "annual", limit = 5 } = params;
     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.
+   * Get historical earnings data
+   *
+   * Provides historical and upcoming earnings announcements including
+   * dates, estimated EPS, and actual EPS. Essential for analyzing
+   * earnings trends and tracking company performance.
+   *
+   * @param params - Earnings historical request parameters
+   * @param params.symbol - The stock symbol to get earnings history for (e.g., 'AAPL', 'MSFT', 'GOOGL')
+   * @param params.limit - Number of periods to retrieve (default: 5)
+   *
+   * @returns Promise resolving to array of historical earnings data with announcement details
+   *
+   * @example
+   * ```typescript
+   * // Get earnings history for Apple
+   * const earningsHistory = await fmp.financial.getEarningsHistorical({ symbol: 'AAPL', limit: 10 });
+   * earningsHistory.data.forEach(earning => {
+   *   console.log(`${earning.date}: Est. ${earning.estimatedEps}, Actual ${earning.actualEps}`);
+   * });
+   *
+   * // Get earnings history for Microsoft
+   * const msftEarnings = await fmp.financial.getEarningsHistorical({ symbol: 'MSFT', limit: 8 });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#earnings-historical-earnings|FMP Earnings Historical Documentation}
    */
-  async getEarningsHistorical({
-    symbol,
-    limit = 5
-  }) {
+  async getEarningsHistorical(params) {
+    const { symbol, limit = 5 } = params;
     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.
+   * Get earnings surprises data
+   *
+   * Provides earnings announcements that exceeded or fell short of
+   * analyst estimates. Essential for analyzing earnings quality and
+   * market reactions to earnings releases.
+   *
+   * @param symbol - The stock symbol to get earnings surprises for (e.g., 'AAPL', 'MSFT', 'GOOGL')
+   *
+   * @returns Promise resolving to array of earnings surprises data with surprise details
+   *
+   * @example
+   * ```typescript
+   * // Get earnings surprises for Apple
+   * const earningsSurprises = await fmp.financial.getEarningsSurprises('AAPL');
+   * earningsSurprises.data.forEach(surprise => {
+   *   console.log(`${surprise.date}: Est. ${surprise.estimatedEps}, Actual ${surprise.actualEps}, Surprise ${surprise.surprisePercentage}%`);
+   * });
+   *
+   * // Get earnings surprises for Microsoft
+   * const msftSurprises = await fmp.financial.getEarningsSurprises('MSFT');
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#earnings-surprises-earnings|FMP Earnings Surprises Documentation}
    */
-  async getEarningsSurprises({
-    symbol
-  }) {
+  async getEarningsSurprises(symbol) {
     return this.client.get(`/earnings-surprises/${symbol}`, "v3");
   }
 };
 
-// src/endpoints/forex.ts
-var ForexEndpoints = class {
+// src/endpoints/etf.ts
+var ETFEndpoints = class {
   constructor(client) {
     this.client = client;
   }
   /**
-   * Get forex quote
-   * @deprecated Use `fmp.quote.getQuote()` instead. This method will be removed in version 0.1.0.
-   * @param params - Parameters for the forex quote request
-   * @returns Forex quote data
+   * Get available ETF holding dates
+   *
+   * Provides a list of dates when ETF holdings are updated and available.
+   * Useful for determining when the most recent holdings data is available
+   * and ensuring you're working with current portfolio information.
+   *
+   * @param symbol - ETF symbol to get holding dates for (e.g., 'SPY', 'VOO', 'QQQ')
+   *
+   * @returns Promise resolving to array of available holding dates
+   *
+   * @example
+   * ```typescript
+   * // Get holding dates for specific ETF
+   * const spyDates = await fmp.etf.getHoldingDates('SPY');
+   * spyDates.data.forEach(date => {
+   *   console.log(`Holdings available: ${date.date}`);
+   * });
+   *
+   * // Get VOO holding dates
+   * const vooDates = await fmp.etf.getHoldingDates('VOO');
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#etf-holding-dates-etf-holdings|FMP ETF Holding Dates Documentation}
    */
-  async getQuote(params) {
-    console.warn(
-      "\u26A0\uFE0F  ForexEndpoints.getQuote() is deprecated. Use fmp.quote.getQuote() instead. This method will be removed in version 0.1.0."
-    );
-    return this.client.get("/quote", "v3", params);
+  async getHoldingDates(symbol) {
+    return this.client.get("/etf-holdings/portfolio-date", "v4", { symbol });
   }
   /**
-   * Get historical forex prices
-   * @deprecated Use `fmp.quote.getHistoricalPrice()` instead. This method will be removed in version 0.1.0.
-   * @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
+   * Get ETF holdings for specific date
+   *
+   * Provides detailed holdings information for an ETF on a specific date.
+   * Includes individual stocks, their weights, shares held, and market values.
+   * Essential for understanding ETF composition and portfolio analysis.
+   *
+   * @param params - ETF holdings request parameters
+   * @param params.symbol - The ETF symbol to get holdings for (e.g., 'SPY', 'VOO', 'QQQ')
+   * @param params.date - The date to get holdings for in YYYY-MM-DD format
+   *
+   * @returns Promise resolving to array of ETF holdings with detailed stock information
+   *
+   * @example
+   * ```typescript
+   * // Get SPY holdings for specific date
+   * const holdings = await fmp.etf.getHoldings({ symbol: 'SPY', date: '2024-01-15' });
+   * holdings.data.forEach(holding => {
+   *   console.log(`${holding.asset}: ${holding.weight}% (${holding.sharesNumber} shares)`);
+   * });
+   *
+   * // Get VOO holdings
+   * const vooHoldings = await fmp.etf.getHoldings({ symbol: 'VOO', date: '2024-01-15' });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#etf-holdings-etf-holdings|FMP ETF Holdings Documentation}
    */
-  async getHistoricalPrice({
-    symbol,
-    from,
-    to
-  }) {
-    console.warn(
-      "\u26A0\uFE0F  ForexEndpoints.getHistoricalPrice() is deprecated. Use fmp.quote.getHistoricalPrice() instead. This method will be removed in version 0.1.0."
-    );
-    const params = {};
-    if (from) params.from = from;
-    if (to) params.to = to;
-    return this.client.get(`/historical-price-full/${symbol}`, "v3", params);
-  }
-};
-
-// src/endpoints/crypto.ts
-var CryptoEndpoints = class {
-  constructor(client) {
-    this.client = client;
+  async getHoldings(params) {
+    const { symbol, date } = params;
+    const queryParams = {};
+    if (symbol) queryParams.symbol = symbol;
+    if (date) queryParams.date = date;
+    return this.client.get("/etf-holdings", "v4", queryParams);
   }
   /**
-   * Get crypto quote
-   * @deprecated Use `fmp.quote.getQuote()` instead. This method will be removed in version 0.1.0.
-   * @param symbol - The crypto symbol to get the quote for
-   * @returns Crypto quote data
+   * Get ETF holdings and components
+   *
+   * Provides all stocks held by a specific ETF including assets, share numbers,
+   * and weight percentages. Essential for understanding ETF composition and
+   * finding which ETFs hold specific stocks.
+   *
+   * @param symbol - The ETF symbol to get holdings for (e.g., 'SPY', 'VOO', 'QQQ')
+   *
+   * @returns Promise resolving to array of ETF holdings with stock details
+   *
+   * @example
+   * ```typescript
+   * // Get SPY holdings
+   * const spyHoldings = await fmp.etf.getHolder('SPY');
+   * spyHoldings.data.forEach(holding => {
+   *   console.log(`${holding.asset}: ${holding.weight}% (${holding.sharesNumber} shares)`);
+   * });
+   *
+   * // Get VOO holdings
+   * const vooHoldings = await fmp.etf.getHolder('VOO');
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#etf-holder-etf-holdings|FMP ETF Holder Documentation}
    */
-  async getQuote({ symbol }) {
-    console.warn(
-      "\u26A0\uFE0F  CryptoEndpoints.getQuote() is deprecated. Use fmp.quote.getQuote() instead. This method will be removed in version 0.1.0."
-    );
-    return this.client.getSingle(`/quote/${symbol}`, "v3");
+  async getHolder(symbol) {
+    return this.client.get(`/etf-holder/${symbol}`, "v3");
   }
   /**
-   * Get historical crypto prices
-   * @deprecated Use `fmp.quote.getHistoricalPrice()` instead. This method will be removed in version 0.1.0.
-   * @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.
+   * Get ETF profile and information
+   *
+   * Provides comprehensive information about an ETF including ticker symbol,
+   * name, expense ratio, assets under management, and other key metrics.
+   * Essential for ETF comparison and due diligence.
+   *
+   * @param symbol - ETF symbol to get profile for (e.g., 'SPY', 'VOO', 'QQQ')
+   *
+   * @returns Promise resolving to ETF profile with detailed information
+   *
+   * @example
+   * ```typescript
+   * // Get SPY profile
+   * const spyProfile = await fmp.etf.getProfile('SPY');
+   * console.log(`SPY AUM: $${spyProfile.data.aum.toLocaleString()}`);
+   * console.log(`Expense Ratio: ${spyProfile.data.expenseRatio}%`);
+   *
+   * // Get VOO profile
+   * const vooProfile = await fmp.etf.getProfile('VOO');
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#etf-information-etf-holdings|FMP ETF Information Documentation}
    */
-  async getHistoricalPrice({
-    symbol,
-    from,
-    to
-  }) {
-    console.warn(
-      "\u26A0\uFE0F  CryptoEndpoints.getHistoricalPrice() is deprecated. Use fmp.quote.getHistoricalPrice() instead. This method will be removed in version 0.1.0."
-    );
-    const params = {};
-    if (from) params.from = from;
-    if (to) params.to = to;
-    return this.client.getSingle(`/historical-price-full/${symbol}`, "v3", params);
-  }
-};
-
-// src/endpoints/etf.ts
-var ETFEndpoints = class {
-  constructor(client) {
-    this.client = client;
-  }
-  /**
-   * 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 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");
+  async getProfile(symbol) {
+    return this.client.getSingle("/etf-info", "v4", { symbol });
   }
   /**
-   * 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({ symbol }) {
-    const params = {};
-    if (symbol) params.symbol = symbol;
-    return this.client.getSingle("/etf-info", "v4", params);
-  }
-  /**
-   * 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.
+   * Get ETF sector weighting and exposure
+   *
+   * Provides a breakdown of an ETF's sector allocation showing the percentage
+   * of assets invested in each sector. Essential for understanding sector
+   * exposure and diversification analysis.
+   *
+   * @param symbol - The ETF symbol to get sector weighting for (e.g., 'SPY', 'VOO', 'QQQ')
+   *
+   * @returns Promise resolving to array of sector weightings with percentage allocations
+   *
+   * @example
+   * ```typescript
+   * // Get SPY sector weightings
+   * const sectorWeightings = await fmp.etf.getSectorWeighting('SPY');
+   * sectorWeightings.data.forEach(sector => {
+   *   console.log(`${sector.sector}: ${sector.weight}%`);
+   * });
+   *
+   * // Get QQQ sector exposure (tech-heavy)
+   * const qqqSectors = await fmp.etf.getSectorWeighting('QQQ');
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#etf-sector-weighting-etf-holdings|FMP ETF Sector Weighting Documentation}
    */
-  async getSectorWeighting({ symbol }) {
+  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.
+   * Get ETF country weighting and exposure
+   *
+   * Provides a breakdown of an ETF's geographic allocation showing the percentage
+   * of assets invested in each country. Essential for understanding international
+   * exposure and geographic diversification.
+   *
+   * @param symbol - The ETF symbol to get country weighting for (e.g., 'SPY', 'VOO', 'EFA')
+   *
+   * @returns Promise resolving to array of country weightings with percentage allocations
+   *
+   * @example
+   * ```typescript
+   * // Get SPY country weightings
+   * const countryWeightings = await fmp.etf.getCountryWeighting('SPY');
+   * countryWeightings.data.forEach(country => {
+   *   console.log(`${country.country}: ${country.weight}%`);
+   * });
+   *
+   * // Get international ETF exposure
+   * const efaCountries = await fmp.etf.getCountryWeighting('EFA');
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#etf-country-weighting-etf-holdings|FMP ETF Country Weighting Documentation}
    */
-  async getCountryWeighting({ symbol }) {
+  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.
+   * Get ETF stock exposure and holdings
+   *
+   * Provides detailed exposure information for a specific stock across all ETFs
+   * that hold it. Includes market value, share numbers, and weight percentages.
+   * Useful for finding which ETFs have exposure to specific stocks.
+   *
+   * @param symbol - The stock symbol to get ETF exposure for (e.g., 'AAPL', 'MSFT', 'GOOGL')
+   *
+   * @returns Promise resolving to array of ETF exposures with detailed holding information
+   *
+   * @example
+   * ```typescript
+   * // Find ETFs that hold Apple
+   * const appleExposure = await fmp.etf.getStockExposure('AAPL');
+   * appleExposure.data.forEach(etf => {
+   *   console.log(`${etf.etfSymbol}: ${etf.weight}% (${etf.sharesNumber} shares)`);
+   * });
+   *
+   * // Find ETFs that hold Microsoft
+   * const msftExposure = await fmp.etf.getStockExposure('MSFT');
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#etf-sector-exposure-etf-holdings|FMP ETF Stock Exposure Documentation}
    */
-  async getStockExposure({ symbol }) {
+  async getStockExposure(symbol) {
     return this.client.get(`/etf-stock-exposure/${symbol}`, "v3");
   }
 };
 
-// src/endpoints/mutual-fund.ts
-var MutualFundEndpoints = class {
-  constructor(client) {
-    this.client = client;
-  }
-  /**
-   * Get mutual fund quote
-   * @deprecated Use `fmp.quote.getQuote()` instead. This method will be removed in a future release.
-   * @param params - Parameters for the mutual fund quote request
-   * @returns Mutual fund quote data
-   */
-  async getQuote(params) {
-    return this.client.get("/quote", "v3", params);
-  }
-  /**
-   * Get mutual fund holders
-   * https://site.financialmodelingprep.com/developer/docs#mutual-fund-holder-mutual-funds-holdings
-   * @param symbol - The symbol of the mutual fund to get the holders for
-   * @returns Mutual fund holders data
-   */
-  async getHolders({ symbol }) {
-    return this.client.get(`/mutual-fund-holder/${symbol}`, "v3");
-  }
-};
-
 // src/endpoints/economic.ts
 var EconomicEndpoints = class {
   constructor(client) {
     this.client = client;
   }
   /**
-   * Get treasury rates
-   * https://site.financialmodelingprep.com/developer/docs#treasury-rates-economics-data
-   * @param from - The start date to get the treasury rates for
-   * @param to - The end date to get the treasury rates for
-   * @returns Treasury rates data
+   * Get treasury rates data
+   *
+   * Provides historical treasury rates for various maturities including
+   * 1-month, 3-month, 6-month, 1-year, 2-year, 3-year, 5-year, 7-year,
+   * 10-year, 20-year, and 30-year treasury bonds. Essential for analyzing
+   * interest rate trends, yield curves, and fixed income investments.
+   *
+   * @param params - Treasury rates request parameters
+   * @param params.from - Start date in YYYY-MM-DD format (optional, defaults to 1 year ago)
+   * @param params.to - End date in YYYY-MM-DD format (optional, defaults to today)
+   *
+   * @returns Promise resolving to array of treasury rates data with yield information
+   *
+   * @example
+   * ```typescript
+   * // Get treasury rates for the last year
+   * const treasuryRates = await fmp.economic.getTreasuryRates({
+   *   from: '2023-01-01',
+   *   to: '2023-12-31'
+   * });
+   * treasuryRates.data.forEach(rate => {
+   *   console.log(`${rate.date}: 10Y ${rate.tenY}%, 2Y ${rate.twoY}%`);
+   * });
+   *
+   * // Get recent treasury rates
+   * const recentRates = await fmp.economic.getTreasuryRates({
+   *   from: '2024-01-01'
+   * });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#treasury-rates-economics-data|FMP Treasury Rates Documentation}
    */
   async getTreasuryRates(params) {
     const { from, to } = params;
@@ -704,12 +1160,47 @@ var EconomicEndpoints = class {
     return this.client.get("/treasury", "v4", queryParams);
   }
   /**
-   * Get economic indicators
-   * https://site.financialmodelingprep.com/developer/docs#economic-indicators-economics-data
-   * @param name - GDP, realGDP, nominalPotentialGDP, realGDPPerCapita, federalFunds, CPI, inflationRate, inflation, retailSales, consumerSentiment, durableGoods, unemploymentRate, totalNonfarmPayroll, initialClaims, industrialProductionTotalIndex, newPrivatelyOwnedHousingUnitsStartedTotalUnits, totalVehicleSales, retailMoneyFunds, smoothedUSRecessionProbabilities, 3MonthOr90DayRatesAndYieldsCertificatesOfDeposit, commercialBankInterestRateOnCreditCardPlansAllAccounts, 30YearFixedRateMortgageAverage, 15YearFixedRateMortgageAverage
-   * @param from - The start date to get the economic indicators for
-   * @param to - The end date to get the economic indicators for
-   * @returns Provides real-time and historical economic data for a variety of economic indicators, such as GDP, unemployment, and inflation.
+   * Get economic indicators data
+   *
+   * Provides real-time and historical economic data for a wide variety of
+   * economic indicators including GDP, unemployment, inflation, retail sales,
+   * and many others. Essential for macroeconomic analysis and understanding
+   * economic trends and cycles.
+   *
+   * @param params - Economic indicators request parameters
+   * @param params.name - The economic indicator to retrieve
+   * @param params.from - Start date in YYYY-MM-DD format (optional, defaults to 1 year ago)
+   * @param params.to - End date in YYYY-MM-DD format (optional, defaults to today)
+   *
+   * @returns Promise resolving to array of economic indicator data with historical values
+   *
+   * @example
+   * ```typescript
+   * // Get GDP data for the last year
+   * const gdpData = await fmp.economic.getEconomicIndicators({
+   *   name: 'GDP',
+   *   from: '2023-01-01',
+   *   to: '2023-12-31'
+   * });
+   * gdpData.data.forEach(gdp => {
+   *   console.log(`${gdp.date}: GDP $${gdp.value.toLocaleString()} billion`);
+   * });
+   *
+   * // Get unemployment rate data
+   * const unemploymentData = await fmp.economic.getEconomicIndicators({
+   *   name: 'unemploymentRate',
+   *   from: '2024-01-01'
+   * });
+   *
+   * // Get inflation rate data
+   * const inflationData = await fmp.economic.getEconomicIndicators({
+   *   name: 'inflationRate',
+   *   from: '2023-01-01',
+   *   to: '2023-12-31'
+   * });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#economic-indicators-economics-data|FMP Economic Indicators Documentation}
    */
   async getEconomicIndicators(params) {
     const { name, from, to } = params;
@@ -726,51 +1217,290 @@ var MarketEndpoints = class {
     this.client = client;
   }
   /**
-   * Get market hours
+   * Get current market hours and trading status
+   *
+   * Provides real-time information about market trading hours, including
+   * whether markets are currently open or closed, trading session times,
+   * and upcoming market holidays. Essential for determining trading
+   * availability and market status.
+   *
+   * @returns Promise resolving to market hours data with trading status and session information
+   *
+   * @example
+   * ```typescript
+   * // Get current market status
+   * const marketHours = await fmp.market.getMarketHours();
+   * console.log(`Market is ${marketHours.data.isTheStockMarketOpen ? 'OPEN' : 'CLOSED'}`);
+   * console.log(`Current time: ${marketHours.data.currentTime}`);
+   * console.log(`Next trading day: ${marketHours.data.nextTradingDay}`);
+   *
+   * // Check if it's a trading day
+   * if (marketHours.data.isTheStockMarketOpen) {
+   *   console.log('Markets are currently open for trading');
+   * } else {
+   *   console.log('Markets are closed');
+   * }
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#market-hours|FMP Market Hours Documentation}
    */
   async getMarketHours() {
     return this.client.get("/market-hours", "v3");
   }
   /**
-   * Get market performance
+   * Get overall market performance data
+   *
+   * Provides comprehensive market performance data including major indices,
+   * market breadth, and key performance metrics. Essential for understanding
+   * overall market sentiment, trends, and daily market activity.
+   *
+   * @returns Promise resolving to array of market performance data with indices and metrics
+   *
+   * @example
+   * ```typescript
+   * // Get overall market performance
+   * const marketPerformance = await fmp.market.getMarketPerformance();
+   * marketPerformance.data.forEach(market => {
+   *   console.log(`${market.index}: ${market.change} (${market.changesPercentage}%)`);
+   *   console.log(`  Open: $${market.open}, High: $${market.dayHigh}, Low: $${market.dayLow}`);
+   * });
+   *
+   * // Find specific indices
+   * const sp500 = marketPerformance.data.find(market => market.index === 'S&P 500');
+   * console.log(`S&P 500 performance: ${sp500?.changesPercentage}%`);
+   *
+   * // Check market sentiment
+   * const gainers = marketPerformance.data.filter(market => market.changesPercentage > 0);
+   * const losers = marketPerformance.data.filter(market => market.changesPercentage < 0);
+   * console.log(`Gaining indices: ${gainers.length}, Losing indices: ${losers.length}`);
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#market-performance|FMP Market Performance Documentation}
    */
   async getMarketPerformance() {
     return this.client.get("/market-performance", "v3");
   }
   /**
-   * 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.
+   * Get top gaining stocks for the current trading day
+   *
+   * Provides a list of stocks that have gained the most value during the
+   * current trading session. Essential for identifying momentum stocks,
+   * tracking market movers, and discovering potential investment opportunities.
+   * Useful for day trading, momentum strategies, and market analysis.
+   *
+   * @returns Promise resolving to array of top gaining stocks with price and percentage change data
+   *
+   * @example
+   * ```typescript
+   * // Get top gainers for the day
+   * const gainers = await fmp.market.getGainers();
+   * console.log(`Top ${gainers.data.length} gaining stocks today:`);
+   *
+   * gainers.data.forEach((stock, index) => {
+   *   console.log(`${index + 1}. ${stock.symbol} (${stock.name})`);
+   *   console.log(`   Price: $${stock.price} | Change: +${stock.change} (${stock.changesPercentage}%)`);
+   *   console.log(`   Volume: ${stock.volume.toLocaleString()}`);
+   * });
+   *
+   * // Find stocks with >10% gains
+   * const bigGainers = gainers.data.filter(stock => stock.changesPercentage > 10);
+   * console.log(`Stocks with >10% gains: ${bigGainers.length}`);
+   *
+   * // Check volume leaders among gainers
+   * const highVolumeGainers = gainers.data.filter(stock => stock.volume > 1000000);
+   * console.log(`High volume gainers (>1M shares): ${highVolumeGainers.length}`);
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#market-biggest-gainers-market-overview|FMP Market Biggest Gainers Documentation}
    */
   async getGainers() {
     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.
+   * Get top losing stocks for the current trading day
+   *
+   * Provides a list of stocks that have lost the most value during the
+   * current trading session. Essential for identifying underperforming stocks,
+   * tracking market decliners, and discovering potential contrarian opportunities.
+   * Useful for risk management, short selling strategies, and market analysis.
+   *
+   * @returns Promise resolving to array of top losing stocks with price and percentage change data
+   *
+   * @example
+   * ```typescript
+   * // Get top losers for the day
+   * const losers = await fmp.market.getLosers();
+   * console.log(`Top ${losers.data.length} losing stocks today:`);
+   *
+   * losers.data.forEach((stock, index) => {
+   *   console.log(`${index + 1}. ${stock.symbol} (${stock.name})`);
+   *   console.log(`   Price: $${stock.price} | Change: ${stock.change} (${stock.changesPercentage}%)`);
+   *   console.log(`   Volume: ${stock.volume.toLocaleString()}`);
+   * });
+   *
+   * // Find stocks with >10% losses
+   * const bigLosers = losers.data.filter(stock => stock.changesPercentage < -10);
+   * console.log(`Stocks with >10% losses: ${bigLosers.length}`);
+   *
+   * // Check for potential oversold conditions
+   * const highVolumeLosers = losers.data.filter(stock => stock.volume > 1000000);
+   * console.log(`High volume losers (>1M shares): ${highVolumeLosers.length}`);
+   *
+   * // Look for potential bounce candidates
+   * const oversoldStocks = losers.data.filter(stock =>
+   *   stock.changesPercentage < -5 && stock.volume > 500000
+   * );
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#market-biggest-losers-market-overview|FMP Market Biggest Losers Documentation}
    */
   async getLosers() {
     return this.client.get("/stock_market/losers", "v3");
   }
   /**
-   * Get most active stocks
+   * Get most actively traded stocks for the current trading day
+   *
+   * Provides a list of stocks with the highest trading volume during the
+   * current trading session. Essential for identifying stocks with high
+   * liquidity, tracking market interest, and discovering stocks with
+   * significant trading activity. Useful for day trading and liquidity analysis.
+   *
+   * @returns Promise resolving to array of most active stocks with volume and price data
+   *
+   * @example
+   * ```typescript
+   * // Get most active stocks for the day
+   * const mostActive = await fmp.market.getMostActive();
+   * console.log(`Top ${mostActive.data.length} most active stocks today:`);
+   *
+   * mostActive.data.forEach((stock, index) => {
+   *   console.log(`${index + 1}. ${stock.symbol} (${stock.name})`);
+   *   console.log(`   Volume: ${stock.volume.toLocaleString()} shares`);
+   *   console.log(`   Price: $${stock.price} | Change: ${stock.change} (${stock.changesPercentage}%)`);
+   *   console.log(`   Avg Volume: ${stock.avgVolume?.toLocaleString() || 'N/A'}`);
+   * });
+   *
+   * // Find stocks with unusual volume (>2x average)
+   * const unusualVolume = mostActive.data.filter(stock =>
+   *   stock.avgVolume && stock.volume > stock.avgVolume * 2
+   * );
+   * console.log(`Stocks with unusual volume: ${unusualVolume.length}`);
+   *
+   * // Check for high volume gainers
+   * const highVolumeGainers = mostActive.data.filter(stock =>
+   *   stock.changesPercentage > 0 && stock.volume > 1000000
+   * );
+   * console.log(`High volume gainers: ${highVolumeGainers.length}`);
+   *
+   * // Find penny stocks with high volume
+   * const pennyStocks = mostActive.data.filter(stock =>
+   *   stock.price < 5 && stock.volume > 500000
+   * );
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#market-most-actives|FMP Market Most Actives Documentation}
    */
   async getMostActive() {
     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.
+   * Get sector performance data for the current trading day
+   *
+   * Provides performance data for all major market sectors including
+   * technology, healthcare, financials, energy, and others. Essential for
+   * sector rotation analysis, identifying leading/lagging sectors, and
+   * understanding market breadth and sector-specific trends.
+   *
+   * @returns Promise resolving to array of sector performance data with percentage changes
+   *
+   * @example
+   * ```typescript
+   * // Get sector performance for the day
+   * const sectorPerformance = await fmp.market.getSectorPerformance();
+   * console.log(`Sector performance for ${sectorPerformance.data.length} sectors:`);
+   *
+   * sectorPerformance.data.forEach(sector => {
+   *   const changeColor = sector.changesPercentage >= 0 ? 'green' : 'red';
+   *   console.log(`${sector.sector}: ${sector.changesPercentage}%`);
+   *   console.log(`  Change: ${sector.changesPercentage >= 0 ? '+' : ''}${sector.changesPercentage}%`);
+   * });
+   *
+   * // Find best performing sectors
+   * const topSectors = sectorPerformance.data
+   *   .sort((a, b) => b.changesPercentage - a.changesPercentage)
+   *   .slice(0, 3);
+   * console.log('Top 3 performing sectors:');
+   * topSectors.forEach((sector, index) => {
+   *   console.log(`${index + 1}. ${sector.sector}: ${sector.changesPercentage}%`);
+   * });
+   *
+   * // Find worst performing sectors
+   * const bottomSectors = sectorPerformance.data
+   *   .sort((a, b) => a.changesPercentage - b.changesPercentage)
+   *   .slice(0, 3);
+   * console.log('Bottom 3 performing sectors:');
+   * bottomSectors.forEach((sector, index) => {
+   *   console.log(`${index + 1}. ${sector.sector}: ${sector.changesPercentage}%`);
+   * });
+   *
+   * // Check for sector rotation
+   * const gainingSectors = sectorPerformance.data.filter(sector => sector.changesPercentage > 0);
+   * const losingSectors = sectorPerformance.data.filter(sector => sector.changesPercentage < 0);
+   * console.log(`Sectors gaining: ${gainingSectors.length}, Sectors losing: ${losingSectors.length}`);
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#sector-performance-market-overview|FMP Sector Performance Documentation}
    */
   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.
+   * Get real-time data for major market indices
+   *
+   * Provides real-time quote data for all major stock market indices including
+   * S&P 500, Dow Jones Industrial Average, NASDAQ Composite, and other global
+   * indices. Essential for tracking overall market performance, understanding
+   * market sentiment, and identifying broad market trends.
+   *
+   * @returns Promise resolving to array of market index data with real-time quotes
+   *
+   * @example
+   * ```typescript
+   * // Get real-time market indices
+   * const marketIndices = await fmp.market.getMarketIndex();
+   * console.log(`Real-time data for ${marketIndices.data.length} major indices:`);
+   *
+   * marketIndices.data.forEach(index => {
+   *   console.log(`${index.symbol} (${index.name}):`);
+   *   console.log(`  Price: $${index.price}`);
+   *   console.log(`  Change: ${index.change} (${index.changesPercentage}%)`);
+   *   console.log(`  Day Range: $${index.dayLow} - $${index.dayHigh}`);
+   *   console.log(`  Volume: ${index.volume?.toLocaleString() || 'N/A'}`);
+   * });
+   *
+   * // Find specific major indices
+   * const sp500 = marketIndices.data.find(index => index.symbol === '^GSPC');
+   * const nasdaq = marketIndices.data.find(index => index.symbol === '^IXIC');
+   * const dowJones = marketIndices.data.find(index => index.symbol === '^DJI');
+   *
+   * console.log(`S&P 500: ${sp500?.price} (${sp500?.changesPercentage}%)`);
+   * console.log(`NASDAQ: ${nasdaq?.price} (${nasdaq?.changesPercentage}%)`);
+   * console.log(`Dow Jones: ${dowJones?.price} (${dowJones?.changesPercentage}%)`);
+   *
+   * // Check market breadth
+   * const gainingIndices = marketIndices.data.filter(index => index.changesPercentage > 0);
+   * const losingIndices = marketIndices.data.filter(index => index.changesPercentage < 0);
+   * console.log(`Indices gaining: ${gainingIndices.length}, Indices losing: ${losingIndices.length}`);
+   *
+   * // Find international indices
+   * const internationalIndices = marketIndices.data.filter(index =>
+   *   !index.symbol.startsWith('^') ||
+   *   index.name.toLowerCase().includes('europe') ||
+   *   index.name.toLowerCase().includes('asia')
+   * );
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#market-index-market-overview|FMP Market Index Documentation}
    */
   async getMarketIndex() {
     return this.client.get("/quotes/index", "v3");
@@ -783,41 +1513,182 @@ var ListEndpoints = class {
     this.client = client;
   }
   /**
-   * Get stock list
-   * https://site.financialmodelingprep.com/developer/docs#symbol-list-stock-list
-   * @returns The stock list
+   * Get comprehensive list of all available stocks
+   *
+   * Provides a complete list of all stocks available on major exchanges including
+   * NYSE, NASDAQ, and other global markets. Essential for discovering available
+   * symbols, building watchlists, or creating stock screening applications.
+   *
+   * @returns Promise resolving to array of stock data with symbol, name, exchange, and price information
+   *
+   * @example
+   * ```typescript
+   * // Get all available stocks
+   * const stocks = await fmp.list.getStockList();
+   * console.log(`Total stocks available: ${stocks.data.length}`);
+   *
+   * // Find specific stocks
+   * const appleStock = stocks.data.find(stock => stock.symbol === 'AAPL');
+   * console.log(`Apple: ${appleStock?.name} (${appleStock?.exchange})`);
+   *
+   * // Filter by exchange
+   * const nasdaqStocks = stocks.data.filter(stock => stock.exchange === 'NASDAQ');
+   * console.log(`NASDAQ stocks: ${nasdaqStocks.length}`);
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#symbol-list-stock-list|FMP Stock List Documentation}
    */
   async getStockList() {
     return this.client.get("/stock/list");
   }
   /**
-   * Get ETF list
-   * https://site.financialmodelingprep.com/developer/docs#exchange-traded-fund-search-stock-list
-   * @returns The ETF list
+   * Get comprehensive list of all available ETFs
+   *
+   * Provides a complete list of all Exchange-Traded Funds (ETFs) available for trading.
+   * Includes ETFs from various asset classes including equity, bond, commodity, and
+   * sector-specific funds. Essential for ETF research and portfolio construction.
+   *
+   * @returns Promise resolving to array of ETF data with symbol, name, exchange, and asset class information
+   *
+   * @example
+   * ```typescript
+   * // Get all available ETFs
+   * const etfs = await fmp.list.getETFList();
+   * console.log(`Total ETFs available: ${etfs.data.length}`);
+   *
+   * // Find specific ETFs
+   * const spyETF = etfs.data.find(etf => etf.symbol === 'SPY');
+   * console.log(`SPY: ${spyETF?.name} (${spyETF?.assetClass})`);
+   *
+   * // Filter by asset class
+   * const equityETFs = etfs.data.filter(etf => etf.assetClass === 'Equity');
+   * console.log(`Equity ETFs: ${equityETFs.length}`);
+   *
+   * // Find sector ETFs
+   * const techETFs = etfs.data.filter(etf =>
+   *   etf.name.toLowerCase().includes('technology') ||
+   *   etf.name.toLowerCase().includes('tech')
+   * );
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#exchange-traded-fund-search-stock-list|FMP ETF List Documentation}
    */
   async getETFList() {
     return this.client.get("/etf/list");
   }
   /**
-   * Get crypto list
-   * https://site.financialmodelingprep.com/developer/docs#cryptocurrencies-list-crypto
-   * @returns The crypto list
+   * Get comprehensive list of all available cryptocurrencies
+   *
+   * Provides a complete list of all cryptocurrencies available for trading.
+   * Includes major cryptocurrencies like Bitcoin, Ethereum, and thousands of altcoins
+   * with their trading pairs against USD and other major currencies.
+   *
+   * @returns Promise resolving to array of cryptocurrency data with symbol, name, and exchange information
+   *
+   * @example
+   * ```typescript
+   * // Get all available cryptocurrencies
+   * const cryptos = await fmp.list.getCryptoList();
+   * console.log(`Total cryptocurrencies available: ${cryptos.data.length}`);
+   *
+   * // Find major cryptocurrencies
+   * const bitcoin = cryptos.data.find(crypto => crypto.symbol === 'BTCUSD');
+   * console.log(`Bitcoin: ${bitcoin?.name} (${bitcoin?.exchange})`);
+   *
+   * const ethereum = cryptos.data.find(crypto => crypto.symbol === 'ETHUSD');
+   * console.log(`Ethereum: ${ethereum?.name} (${ethereum?.exchange})`);
+   *
+   * // Filter by exchange
+   * const binanceCryptos = cryptos.data.filter(crypto => crypto.exchange === 'Binance');
+   * console.log(`Binance cryptocurrencies: ${binanceCryptos.length}`);
+   *
+   * // Find altcoins
+   * const altcoins = cryptos.data.filter(crypto =>
+   *   !['BTCUSD', 'ETHUSD', 'USDTUSD', 'USDCUSD'].includes(crypto.symbol)
+   * );
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#cryptocurrencies-list-crypto|FMP Cryptocurrency List Documentation}
    */
   async getCryptoList() {
     return this.client.get("/symbol/available-cryptocurrencies");
   }
   /**
-   * Get forex list
-   * https://site.financialmodelingprep.com/developer/docs#forex-list-forex
-   * @returns The forex list
+   * Get comprehensive list of all available forex currency pairs
+   *
+   * Provides a complete list of all foreign exchange currency pairs available for trading.
+   * Includes major, minor, and exotic currency pairs with their base and quote currencies.
+   * Essential for forex trading, currency analysis, and international market research.
+   *
+   * @returns Promise resolving to array of forex data with currency pair symbols and exchange information
+   *
+   * @example
+   * ```typescript
+   * // Get all available forex pairs
+   * const forexPairs = await fmp.list.getForexList();
+   * console.log(`Total forex pairs available: ${forexPairs.data.length}`);
+   *
+   * // Find major currency pairs
+   * const eurUsd = forexPairs.data.find(pair => pair.symbol === 'EURUSD');
+   * console.log(`EUR/USD: ${eurUsd?.name} (${eurUsd?.exchange})`);
+   *
+   * const gbpUsd = forexPairs.data.find(pair => pair.symbol === 'GBPUSD');
+   * console.log(`GBP/USD: ${gbpUsd?.name} (${gbpUsd?.exchange})`);
+   *
+   * // Filter major pairs (USD as quote currency)
+   * const majorPairs = forexPairs.data.filter(pair =>
+   *   pair.symbol.endsWith('USD') && pair.symbol.length === 6
+   * );
+   * console.log(`Major pairs: ${majorPairs.length}`);
+   *
+   * // Find exotic pairs
+   * const exoticPairs = forexPairs.data.filter(pair =>
+   *   pair.symbol.includes('ZAR') || pair.symbol.includes('TRY') || pair.symbol.includes('BRL')
+   * );
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#forex-list-forex|FMP Forex List Documentation}
    */
   async getForexList() {
     return this.client.get("/symbol/available-forex-currency-pairs");
   }
   /**
-   * Get available indexes list
-   * https://site.financialmodelingprep.com/developer/docs#available-indexes
-   * @returns The available indexes list
+   * Get comprehensive list of all available market indexes
+   *
+   * Provides a complete list of all market indexes available for tracking and analysis.
+   * Includes major global indexes like S&P 500, NASDAQ, Dow Jones, as well as
+   * international indexes, sector indexes, and specialized market benchmarks.
+   *
+   * @returns Promise resolving to array of index data with symbol, name, and exchange information
+   *
+   * @example
+   * ```typescript
+   * // Get all available indexes
+   * const indexes = await fmp.list.getAvailableIndexes();
+   * console.log(`Total indexes available: ${indexes.data.length}`);
+   *
+   * // Find major US indexes
+   * const sp500 = indexes.data.find(index => index.symbol === '^GSPC');
+   * console.log(`S&P 500: ${sp500?.name} (${sp500?.exchange})`);
+   *
+   * const nasdaq = indexes.data.find(index => index.symbol === '^IXIC');
+   * console.log(`NASDAQ: ${nasdaq?.name} (${nasdaq?.exchange})`);
+   *
+   * const dowJones = indexes.data.find(index => index.symbol === '^DJI');
+   * console.log(`Dow Jones: ${dowJones?.name} (${dowJones?.exchange})`);
+   *
+   * // Filter by exchange
+   * const nyseIndexes = indexes.data.filter(index => index.exchange === 'NYSE');
+   * console.log(`NYSE indexes: ${nyseIndexes.length}`);
+   *
+   * // Find sector indexes
+   * const techIndexes = indexes.data.filter(index =>
+   *   index.name.toLowerCase().includes('technology') ||
+   *   index.name.toLowerCase().includes('tech')
+   * );
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#available-indexes|FMP Available Indexes Documentation}
    */
   async getAvailableIndexes() {
     return this.client.get("/symbol/available-indexes");
@@ -830,82 +1701,244 @@ var CalendarEndpoints = class {
     this.client = client;
   }
   /**
-   * Get earnings calendar
-   * https://site.financialmodelingprep.com/developer/docs#earnings-calendar-earnings
-   * @param from - The start date to get the earnings calendar for
-   * @param to - The end date to get the earnings calendar for
-   * @returns The earnings calendar
+   * Get earnings calendar data
+   *
+   * Provides upcoming earnings announcements for all publicly traded companies
+   * within a specified date range. Essential for tracking earnings season,
+   * market events, and investment timing decisions.
+   *
+   * @param params - Earnings calendar request parameters
+   * @param params.from - Start date in YYYY-MM-DD format (optional, defaults to today)
+   * @param params.to - End date in YYYY-MM-DD format (optional, defaults to 30 days from today)
+   *
+   * @returns Promise resolving to array of earnings calendar data with announcement details
+   *
+   * @example
+   * ```typescript
+   * // Get earnings calendar for next week
+   * const earningsCalendar = await fmp.calendar.getEarningsCalendar({
+   *   from: '2024-01-15',
+   *   to: '2024-01-22'
+   * });
+   * earningsCalendar.data.forEach(earning => {
+   *   console.log(`${earning.date}: ${earning.symbol} - Est. EPS: ${earning.estimatedEps}`);
+   * });
+   *
+   * // Get earnings calendar for current month
+   * const monthlyEarnings = await fmp.calendar.getEarningsCalendar({
+   *   from: '2024-01-01',
+   *   to: '2024-01-31'
+   * });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#earnings-calendar-earnings|FMP Earnings Calendar Documentation}
    */
-  async getEarningsCalendar({ from, to } = {}) {
-    const params = {};
-    if (from) params.from = from;
-    if (to) params.to = to;
-    return this.client.get("/earning_calendar", "v3", params);
+  async getEarningsCalendar(params = {}) {
+    const { from, to } = params;
+    const queryParams = {};
+    if (from) queryParams.from = from;
+    if (to) queryParams.to = to;
+    return this.client.get("/earning_calendar", "v3", queryParams);
   }
   /**
-   * Get earnings confirmed
-   * https://site.financialmodelingprep.com/developer/docs#earnings-confirmed-earnings
-   * @param from - The start date to get the earnings confirmed for
-   * @param to - The end date to get the earnings confirmed for
-   * @returns The earnings confirmed
+   * Get confirmed earnings calendar data
+   *
+   * Provides confirmed earnings announcements with verified dates and times.
+   * These are earnings announcements that have been officially confirmed
+   * by companies, providing more reliable scheduling information.
+   *
+   * @param params - Confirmed earnings calendar request parameters
+   * @param params.from - Start date in YYYY-MM-DD format (optional, defaults to today)
+   * @param params.to - End date in YYYY-MM-DD format (optional, defaults to 30 days from today)
+   *
+   * @returns Promise resolving to array of confirmed earnings calendar data
+   *
+   * @example
+   * ```typescript
+   * // Get confirmed earnings for next week
+   * const confirmedEarnings = await fmp.calendar.getEarningsConfirmed({
+   *   from: '2024-01-15',
+   *   to: '2024-01-22'
+   * });
+   * confirmedEarnings.data.forEach(earning => {
+   *   console.log(`${earning.date}: ${earning.symbol} - Confirmed: ${earning.time}`);
+   * });
+   *
+   * // Get confirmed earnings for current month
+   * const monthlyConfirmed = await fmp.calendar.getEarningsConfirmed({
+   *   from: '2024-01-01',
+   *   to: '2024-01-31'
+   * });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#earnings-confirmed-earnings|FMP Earnings Confirmed Documentation}
    */
-  async getEarningsConfirmed({ from, to } = {}) {
-    const params = {};
-    if (from) params.from = from;
-    if (to) params.to = to;
-    return this.client.get("/earning-calendar-confirmed", "v4", params);
+  async getEarningsConfirmed(params = {}) {
+    const { from, to } = params;
+    const queryParams = {};
+    if (from) queryParams.from = from;
+    if (to) queryParams.to = to;
+    return this.client.get("/earning-calendar-confirmed", "v4", queryParams);
   }
   /**
-   * Get dividends calendar
-   * https://site.financialmodelingprep.com/developer/docs#dividends-calendar-dividends
-   * @param from - The start date to get the dividends calendar for
-   * @param to - The end date to get the dividends calendar for
-   * @returns The dividends calendar
+   * Get dividends calendar data
+   *
+   * Provides upcoming dividend payments and ex-dividend dates for all
+   * publicly traded companies within a specified date range. Essential
+   * for dividend investors and income-focused strategies.
+   *
+   * @param params - Dividends calendar request parameters
+   * @param params.from - Start date in YYYY-MM-DD format (optional, defaults to today)
+   * @param params.to - End date in YYYY-MM-DD format (optional, defaults to 30 days from today)
+   *
+   * @returns Promise resolving to array of dividends calendar data with payment details
+   *
+   * @example
+   * ```typescript
+   * // Get dividends calendar for next week
+   * const dividendsCalendar = await fmp.calendar.getDividendsCalendar({
+   *   from: '2024-01-15',
+   *   to: '2024-01-22'
+   * });
+   * dividendsCalendar.data.forEach(dividend => {
+   *   console.log(`${dividend.date}: ${dividend.symbol} - Amount: $${dividend.amount}`);
+   * });
+   *
+   * // Get dividends calendar for current month
+   * const monthlyDividends = await fmp.calendar.getDividendsCalendar({
+   *   from: '2024-01-01',
+   *   to: '2024-01-31'
+   * });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#dividends-calendar-dividends|FMP Dividends Calendar Documentation}
    */
-  async getDividendsCalendar({ from, to } = {}) {
-    const params = {};
-    if (from) params.from = from;
-    if (to) params.to = to;
-    return this.client.get("/stock_dividend_calendar", "v3", params);
+  async getDividendsCalendar(params = {}) {
+    const { from, to } = params;
+    const queryParams = {};
+    if (from) queryParams.from = from;
+    if (to) queryParams.to = to;
+    return this.client.get("/stock_dividend_calendar", "v3", queryParams);
   }
   /**
-   * Get economics calendar
-   * https://site.financialmodelingprep.com/developer/docs#economics-calendar-economics-data
-   * @param from - The start date to get the economics calendar for
-   * @param to - The end date to get the economics calendar for
-   * @returns The economics calendar
+   * Get economic calendar data
+   *
+   * Provides upcoming economic events, indicators, and data releases
+   * that can impact financial markets. Essential for understanding
+   * market-moving events and economic trends.
+   *
+   * @param params - Economic calendar request parameters
+   * @param params.from - Start date in YYYY-MM-DD format (optional, defaults to today)
+   * @param params.to - End date in YYYY-MM-DD format (optional, defaults to 30 days from today)
+   *
+   * @returns Promise resolving to array of economic calendar data with event details
+   *
+   * @example
+   * ```typescript
+   * // Get economic calendar for next week
+   * const economicCalendar = await fmp.calendar.getEconomicsCalendar({
+   *   from: '2024-01-15',
+   *   to: '2024-01-22'
+   * });
+   * economicCalendar.data.forEach(event => {
+   *   console.log(`${event.date}: ${event.event} - Country: ${event.country}`);
+   * });
+   *
+   * // Get economic calendar for current month
+   * const monthlyEconomic = await fmp.calendar.getEconomicsCalendar({
+   *   from: '2024-01-01',
+   *   to: '2024-01-31'
+   * });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#economics-calendar-economics-data|FMP Economic Calendar Documentation}
    */
-  async getEconomicsCalendar({ from, to } = {}) {
-    const params = {};
-    if (from) params.from = from;
-    if (to) params.to = to;
-    return this.client.get("/economic_calendar", "v3", params);
+  async getEconomicsCalendar(params = {}) {
+    const { from, to } = params;
+    const queryParams = {};
+    if (from) queryParams.from = from;
+    if (to) queryParams.to = to;
+    return this.client.get("/economic_calendar", "v3", queryParams);
   }
   /**
-   * Get IPO calendar
-   * https://site.financialmodelingprep.com/developer/docs#ipo-calender-by-ipo-calendar
-   * @param from - The start date to get the IPO calendar for
-   * @param to - The end date to get the IPO calendar for
-   * @returns The IPO calendar
+   * Get IPO calendar data
+   *
+   * Provides upcoming initial public offerings (IPOs) and their details
+   * within a specified date range. Essential for tracking new market
+   * entrants and investment opportunities in newly public companies.
+   *
+   * @param params - IPO calendar request parameters
+   * @param params.from - Start date in YYYY-MM-DD format (optional, defaults to today)
+   * @param params.to - End date in YYYY-MM-DD format (optional, defaults to 30 days from today)
+   *
+   * @returns Promise resolving to array of IPO calendar data with offering details
+   *
+   * @example
+   * ```typescript
+   * // Get IPO calendar for next week
+   * const ipoCalendar = await fmp.calendar.getIPOCalendar({
+   *   from: '2024-01-15',
+   *   to: '2024-01-22'
+   * });
+   * ipoCalendar.data.forEach(ipo => {
+   *   console.log(`${ipo.date}: ${ipo.symbol} - Price: $${ipo.price}, Shares: ${ipo.shares.toLocaleString()}`);
+   * });
+   *
+   * // Get IPO calendar for current month
+   * const monthlyIPOs = await fmp.calendar.getIPOCalendar({
+   *   from: '2024-01-01',
+   *   to: '2024-01-31'
+   * });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#ipo-calender-by-ipo-calendar|FMP IPO Calendar Documentation}
    */
-  async getIPOCalendar({ from, to } = {}) {
-    const params = {};
-    if (from) params.from = from;
-    if (to) params.to = to;
-    return this.client.get("/ipo_calendar", "v3", params);
+  async getIPOCalendar(params = {}) {
+    const { from, to } = params;
+    const queryParams = {};
+    if (from) queryParams.from = from;
+    if (to) queryParams.to = to;
+    return this.client.get("/ipo_calendar", "v3", queryParams);
   }
   /**
-   * Get stock splits calendar
-   * https://site.financialmodelingprep.com/developer/docs#splits-calendar-splits
-   * @param from - The start date to get the stock splits calendar for
-   * @param to - The end date to get the stock splits calendar for
-   * @returns The stock splits calendar
+   * Get stock splits calendar data
+   *
+   * Provides upcoming stock splits for publicly traded companies within
+   * a specified date range. Essential for understanding corporate actions
+   * that affect share prices and trading dynamics.
+   *
+   * @param params - Stock splits calendar request parameters
+   * @param params.from - Start date in YYYY-MM-DD format (optional, defaults to today)
+   * @param params.to - End date in YYYY-MM-DD format (optional, defaults to 30 days from today)
+   *
+   * @returns Promise resolving to array of stock splits calendar data with split details
+   *
+   * @example
+   * ```typescript
+   * // Get stock splits calendar for next week
+   * const splitsCalendar = await fmp.calendar.getSplitsCalendar({
+   *   from: '2024-01-15',
+   *   to: '2024-01-22'
+   * });
+   * splitsCalendar.data.forEach(split => {
+   *   console.log(`${split.date}: ${split.symbol} - Ratio: ${split.numerator}:${split.denominator}`);
+   * });
+   *
+   * // Get stock splits calendar for current month
+   * const monthlySplits = await fmp.calendar.getSplitsCalendar({
+   *   from: '2024-01-01',
+   *   to: '2024-01-31'
+   * });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#splits-calendar-splits|FMP Stock Splits Calendar Documentation}
    */
-  async getSplitsCalendar({ from, to } = {}) {
-    const params = {};
-    if (from) params.from = from;
-    if (to) params.to = to;
-    return this.client.get("/stock_split_calendar", "v3", params);
+  async getSplitsCalendar(params = {}) {
+    const { from, to } = params;
+    const queryParams = {};
+    if (from) queryParams.from = from;
+    if (to) queryParams.to = to;
+    return this.client.get("/stock_split_calendar", "v3", queryParams);
   }
 };
 
@@ -915,97 +1948,243 @@ var CompanyEndpoints = class {
     this.client = client;
   }
   /**
-   * Get company profile
-   * https://site.financialmodelingprep.com/developer/docs#company-profile-company-information
-   * @param symbol - The stock symbol to get the profile for
-   * @returns Get a comprehensive overview of a company with our Company Profile endpoint. This endpoint provides key information such as price, beta, market capitalization, description, headquarters, and more.
+   * Get comprehensive company profile and information
+   *
+   * Provides detailed company information including financial metrics, business description,
+   * headquarters location, and key performance indicators. Essential for fundamental analysis
+   * and understanding a company's business model and market position.
+   *
+   * @param symbol - The stock symbol to get the profile for (e.g., 'AAPL', 'MSFT', 'GOOGL')
+   *
+   * @returns Promise resolving to comprehensive company profile with financial and business information
+   *
+   * @example
+   * ```typescript
+   * // Get Apple's company profile
+   * const profile = await fmp.company.getCompanyProfile('AAPL');
+   * console.log(`Company: ${profile.data.companyName}`);
+   * console.log(`Industry: ${profile.data.industry}`);
+   * console.log(`Market Cap: $${profile.data.mktCap.toLocaleString()}`);
+   * console.log(`Description: ${profile.data.description.substring(0, 100)}...`);
+   *
+   * // Get Microsoft's profile
+   * const msftProfile = await fmp.company.getCompanyProfile('MSFT');
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#company-profile-company-information|FMP Company Profile Documentation}
    */
-  async getCompanyProfile({ symbol }) {
+  async getCompanyProfile(symbol) {
     return this.client.getSingle(`/profile/${symbol}`, "v3");
   }
   /**
-   * Get executive compensation
-   * https://site.financialmodelingprep.com/developer/docs#executive-compensation-company-information
-   * @param symbol - The stock symbol to get the executive compensation for
-   * @returns Understand how a company compensates its executives with our Executive Compensation endpoint. This endpoint provides information such as salary, bonus, and stock options for each executive.
+   * Get executive compensation and governance information
+   *
+   * Provides detailed compensation data for company executives including salary, bonuses,
+   * stock options, and other benefits. Essential for governance analysis and understanding
+   * executive pay structures and alignment with shareholder interests.
+   *
+   * @param symbol - The stock symbol to get executive compensation for (e.g., 'AAPL', 'MSFT', 'TSLA')
+   *
+   * @returns Promise resolving to array of executive compensation data with detailed pay information
+   *
+   * @example
+   * ```typescript
+   * // Get Apple's executive compensation
+   * const compensation = await fmp.company.getExecutiveCompensation('AAPL');
+   * compensation.data.forEach(exec => {
+   *   console.log(`${exec.name} (${exec.title}):`);
+   *   console.log(`  Salary: $${exec.salary.toLocaleString()}`);
+   *   console.log(`  Bonus: $${exec.bonus.toLocaleString()}`);
+   *   console.log(`  Stock Options: $${exec.stockAwards.toLocaleString()}`);
+   * });
+   *
+   * // Get Tesla's executive compensation
+   * const teslaComp = await fmp.company.getExecutiveCompensation('TSLA');
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#executive-compensation-company-information|FMP Executive Compensation Documentation}
    */
-  async getExecutiveCompensation({
-    symbol
-  }) {
-    const params = { symbol };
-    return this.client.get(`/governance/executive_compensation`, "v4", params);
+  async getExecutiveCompensation(symbol) {
+    return this.client.get(`/governance/executive_compensation`, "v4", { symbol });
   }
   /**
-   * Get company notes
-   * https://site.financialmodelingprep.com/developer/docs#company-notes-company-information
-   * @param symbol - The stock symbol to get the notes for
-   * @returns Stay up-to-date on a company's financial condition, operations, and risks with our Company Notes endpoint. This endpoint provides information about notes reported by a company in their financial statements.
+   * Get company notes and financial disclosures
+   *
+   * Provides important notes and disclosures from company financial statements.
+   * These notes contain critical information about accounting policies, risks,
+   * contingencies, and other material information that affects financial analysis.
+   *
+   * @param symbol - The stock symbol to get notes for (e.g., 'AAPL', 'MSFT', 'JPM')
+   *
+   * @returns Promise resolving to array of company notes with detailed disclosure information
+   *
+   * @example
+   * ```typescript
+   * // Get Apple's company notes
+   * const notes = await fmp.company.getCompanyNotes('AAPL');
+   * notes.data.forEach(note => {
+   *   console.log(`Note ${note.noteNumber}: ${note.noteTitle}`);
+   *   console.log(`  Content: ${note.noteContent.substring(0, 100)}...`);
+   * });
+   *
+   * // Get JPMorgan's notes
+   * const jpmNotes = await fmp.company.getCompanyNotes('JPM');
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#company-notes-company-information|FMP Company Notes Documentation}
    */
-  async getCompanyNotes({ symbol }) {
-    const params = { symbol };
-    return this.client.get(`/company-notes`, "v4", params);
+  async getCompanyNotes(symbol) {
+    return this.client.get(`/company-notes`, "v4", { symbol });
   }
   /**
-   * Get historical employee count
-   * https://site.financialmodelingprep.com/developer/docs#historical-employee-company-information
-   * @param symbol - The stock symbol to get the historical employee count for
-   * @returns Track a company's employee count over time with our Historical Employee Count endpoint. This endpoint provides information about the number of employees a company has had each year.
+   * Get historical employee count data
+   *
+   * Provides historical data on company employee counts over time.
+   * Useful for analyzing company growth, operational efficiency, and workforce trends.
+   * Employee count is often a key indicator of company expansion or contraction.
+   *
+   * @param symbol - The stock symbol to get historical employee count for (e.g., 'AAPL', 'MSFT', 'AMZN')
+   *
+   * @returns Promise resolving to array of historical employee count data with year-by-year information
+   *
+   * @example
+   * ```typescript
+   * // Get Apple's employee count history
+   * const employees = await fmp.company.getHistoricalEmployeeCount('AAPL');
+   * employees.data.forEach(year => {
+   *   console.log(`${year.year}: ${year.employeeCount.toLocaleString()} employees`);
+   * });
+   *
+   * // Get Amazon's employee growth
+   * const amazonEmployees = await fmp.company.getHistoricalEmployeeCount('AMZN');
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#historical-employee-company-information|FMP Historical Employee Count Documentation}
    */
-  async getHistoricalEmployeeCount({
-    symbol
-  }) {
-    const params = { symbol };
-    return this.client.get(`/historical/employee_count`, "v4", params);
+  async getHistoricalEmployeeCount(symbol) {
+    return this.client.get(`/historical/employee_count`, "v4", { symbol });
   }
   /**
-   * Get shares float
-   * https://site.financialmodelingprep.com/developer/docs#company-share-float-share-float
-   * @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.
+   * Get current shares float information
+   *
+   * Provides the total number of shares that are publicly traded (float) for a company.
+   * The float is calculated by subtracting restricted shares from total outstanding shares.
+   * Important for understanding liquidity, volatility, and trading dynamics.
+   *
+   * @param symbol - The stock symbol to get shares float for (e.g., 'AAPL', 'TSLA', 'NVDA')
+   *
+   * @returns Promise resolving to shares float data with current float information
+   *
+   * @example
+   * ```typescript
+   * // Get Apple's shares float
+   * const float = await fmp.company.getSharesFloat('AAPL');
+   * console.log(`Float: ${float.data.sharesFloat.toLocaleString()} shares`);
+   * console.log(`Outstanding: ${float.data.sharesOutstanding.toLocaleString()} shares`);
+   * console.log(`Restricted: ${float.data.restrictedShares.toLocaleString()} shares`);
+   *
+   * // Get Tesla's float
+   * const teslaFloat = await fmp.company.getSharesFloat('TSLA');
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#company-share-float-share-float|FMP Shares Float Documentation}
    */
-  async getSharesFloat({ symbol }) {
-    const params = { symbol };
-    return this.client.getSingle(`/shares_float`, "v4", params);
+  async getSharesFloat(symbol) {
+    return this.client.getSingle(`/shares_float`, "v4", { symbol });
   }
   /**
-   * Get historical shares float
-   * https://site.financialmodelingprep.com/developer/docs#company-historical-share-float
-   * @param symbol - The stock symbol to get the historical shares float for
-   * @returns The FMP Historical Share Float endpoint provides historical data on the 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.
+   * Get historical shares float data
+   *
+   * Provides historical data on company shares float over time.
+   * Useful for analyzing changes in liquidity, share issuance, and corporate actions
+   * that affect the number of publicly traded shares.
+   *
+   * @param symbol - The stock symbol to get historical shares float for (e.g., 'AAPL', 'TSLA', 'NVDA')
+   *
+   * @returns Promise resolving to array of historical shares float data with date-by-date information
+   *
+   * @example
+   * ```typescript
+   * // Get Apple's historical float
+   * const historicalFloat = await fmp.company.getHistoricalSharesFloat('AAPL');
+   * historicalFloat.data.forEach(entry => {
+   *   console.log(`${entry.date}: ${entry.sharesFloat.toLocaleString()} shares`);
+   * });
+   *
+   * // Get Tesla's float history
+   * const teslaHistory = await fmp.company.getHistoricalSharesFloat('TSLA');
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#company-historical-share-float|FMP Historical Shares Float Documentation}
    */
-  async getHistoricalSharesFloat({
-    symbol
-  }) {
-    const params = { symbol };
-    return this.client.get(`/historical/shares_float`, "v4", params);
+  async getHistoricalSharesFloat(symbol) {
+    return this.client.get(`/historical/shares_float`, "v4", { symbol });
   }
   /**
-   * Get earnings call transcript
-   * https://site.financialmodelingprep.com/developer/docs#earnings-transcript-earnings-transcripts
-   * @param symbol - The stock symbol to get the earnings call transcript for
-   * @param year - The year of the earnings call
-   * @param quarter - The quarter of the earnings call
-   * @returns The FMP Earnings Call Transcript endpoint provides the transcript of a company's earnings call.
-   */
-  async getEarningsCallTranscript({
-    symbol,
-    year,
-    quarter
-  }) {
-    const params = { year, quarter };
-    return this.client.getSingle(`/earning_call_transcript/${symbol}`, "v3", params);
-  }
+   * Get earnings call transcript for specific quarter
+   *
+   * Provides the full transcript of a company's earnings conference call.
+   * Contains detailed Q&A sessions, management commentary, and insights into
+   * company performance, strategy, and future outlook.
+   *
+   * @param params - Earnings call transcript request parameters
+   * @param params.symbol - The stock symbol to get transcript for (e.g., 'AAPL', 'MSFT', 'TSLA')
+   * @param params.year - The year of the earnings call (e.g., 2024)
+   * @param params.quarter - The quarter of the earnings call (1, 2, 3, or 4)
+   *
+   * @returns Promise resolving to earnings call transcript with full text content
+   *
+   * @example
+   * ```typescript
+   * // Get Apple's Q1 2024 earnings call
+   * const transcript = await fmp.company.getEarningsCallTranscript({
+   *   symbol: 'AAPL',
+   *   year: 2024,
+   *   quarter: 1
+   * });
+   * console.log(`Transcript: ${transcript.data[0].content.substring(0, 200)}...`);
+   *
+   * // Get Tesla's Q4 2023 earnings call
+   * const teslaTranscript = await fmp.company.getEarningsCallTranscript({
+   *   symbol: 'TSLA',
+   *   year: 2023,
+   *   quarter: 4
+   * });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#earnings-transcript-earnings-transcripts|FMP Earnings Call Transcript Documentation}
+   */
+  async getEarningsCallTranscript(params) {
+    const { symbol, year, quarter } = params;
+    return this.client.getSingle(`/earning_call_transcript/${symbol}`, "v3", { year, quarter });
+  }
   /**
-   * Get company transcript dates
-   * https://site.financialmodelingprep.com/developer/docs#transcript-dates-earnings-transcripts
-   * @param symbol - The stock symbol to get the transcript data for
-   * @returns The FMP Company Transcript Data endpoint provides the transcript data for a company's earnings call.
+   * Get available earnings call transcript dates
+   *
+   * Provides a list of all available earnings call transcript dates for a company.
+   * Useful for discovering which quarters have transcripts available before
+   * requesting the full transcript content.
+   *
+   * @param symbol - The stock symbol to get transcript dates for (e.g., 'AAPL', 'MSFT', 'TSLA')
+   *
+   * @returns Promise resolving to array of available transcript dates with quarter information
+   *
+   * @example
+   * ```typescript
+   * // Get Apple's available transcript dates
+   * const transcriptDates = await fmp.company.getCompanyTranscriptData('AAPL');
+   * transcriptDates.data.forEach(date => {
+   *   console.log(`Q${date.quarter} ${date.year}: ${date.date}`);
+   * });
+   *
+   * // Get Microsoft's transcript availability
+   * const msftDates = await fmp.company.getCompanyTranscriptData('MSFT');
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#transcript-dates-earnings-transcripts|FMP Company Transcript Data Documentation}
    */
-  async getCompanyTranscriptData({
-    symbol
-  }) {
-    const params = { symbol };
-    return this.client.getSingle(`/earning_call_transcript`, "v4", params);
+  async getCompanyTranscriptData(symbol) {
+    return this.client.getSingle(`/earning_call_transcript`, "v4", { symbol });
   }
 };
 
@@ -1015,18 +2194,58 @@ var QuoteEndpoints = class {
     this.client = client;
   }
   /**
-   * Get quote for any asset type (stock, crypto, forex, commodity, ETF)
-   * @param params - Parameters for the quote request
-   * @returns Quote data for the specified asset
+   * Get real-time quote data for any asset type (stocks, crypto, forex, commodities, ETFs)
+   *
+   * This endpoint provides current market data including price, volume, market cap, and key metrics.
+   * Works with any valid symbol across all supported asset classes.
+   *
+   * @param symbol - The trading symbol (e.g., 'AAPL', 'BTCUSD', 'EURUSD', 'GCUSD', 'SPY')
+   *
+   * @returns Promise resolving to quote data with current price, volume, market cap, and performance metrics
+   *
+   * @example
+   * ```typescript
+   * // Get stock quote
+   * const aaplQuote = await fmp.quote.getQuote('AAPL');
+   *
+   * // Get crypto quote
+   * const btcQuote = await fmp.quote.getQuote('BTCUSD');
+   *
+   * // Get forex quote
+   * const eurQuote = await fmp.quote.getQuote('EURUSD');
+   * ```
    */
-  async getQuote(params) {
-    const { symbol } = params;
+  async getQuote(symbol) {
     return this.client.getSingle(`/quote/${symbol}`, "v3");
   }
   /**
-   * Get historical prices for any asset type
-   * @param params - Parameters for the historical price request
-   * @returns Historical price data for the specified asset
+   * Get historical price data for any asset type with customizable date range
+   *
+   * Retrieves daily OHLCV (Open, High, Low, Close, Volume) data for the specified symbol.
+   * Data includes adjusted close prices, volume, and percentage changes.
+   *
+   * @param params - Historical price request parameters
+   * @param params.symbol - The trading symbol to get historical data for
+   * @param params.from - Start date in YYYY-MM-DD format (optional, defaults to 1 year ago)
+   * @param params.to - End date in YYYY-MM-DD format (optional, defaults to today)
+   *
+   * @returns Promise resolving to historical price data with daily OHLCV information
+   *
+   * @example
+   * ```typescript
+   * // Get last year's data
+   * const history = await fmp.quote.getHistoricalPrice({
+   *   symbol: 'AAPL',
+   *   from: '2023-01-01',
+   *   to: '2023-12-31'
+   * });
+   *
+   * // Get recent data (last 30 days)
+   * const recent = await fmp.quote.getHistoricalPrice({
+   *   symbol: 'BTCUSD',
+   *   from: '2024-01-01'
+   * });
+   * ```
    */
   async getHistoricalPrice(params) {
     const { symbol, from, to } = params;
@@ -1036,18 +2255,66 @@ var QuoteEndpoints = class {
     return this.client.getSingle(`/historical-price-full/${symbol}`, "v3", queryParams);
   }
   /**
-   * Get multiple quotes for any asset type
-   * @param symbols - Array of symbols to get quotes for
-   * @returns Array of quote data
+   * Get real-time quotes for multiple symbols in a single request
+   *
+   * Efficiently retrieve quote data for multiple assets across different asset classes.
+   * Useful for portfolio tracking, market monitoring, or batch data collection.
+   *
+   * @param symbols - Array of trading symbols to get quotes for
+   *
+   * @returns Promise resolving to an array of quote data for all requested symbols
+   *
+   * @example
+   * ```typescript
+   * // Get quotes for a mixed portfolio
+   * const quotes = await fmp.quote.getQuotes([
+   *   'AAPL',    // Stock
+   *   'BTCUSD',  // Crypto
+   *   'EURUSD',  // Forex
+   *   'SPY'      // ETF
+   * ]);
+   *
+   * // Get quotes for tech stocks
+   * const techQuotes = await fmp.quote.getQuotes([
+   *   'AAPL', 'MSFT', 'GOOGL', 'AMZN', 'TSLA'
+   * ]);
+   * ```
    */
   async getQuotes(symbols) {
     const symbolsParam = symbols.join(",");
     return this.client.get(`/quote/${symbolsParam}`, "v3");
   }
   /**
-   * Get intraday data for any asset type
-   * @param params - Parameters for the intraday request
-   * @returns Intraday price data for the specified asset
+   * Get intraday price data with customizable time intervals
+   *
+   * Retrieves intraday OHLCV data at specified intervals (1min to 4hour).
+   * Perfect for technical analysis, day trading, or short-term price monitoring.
+   *
+   * @param params - Intraday request parameters
+   * @param params.symbol - The trading symbol to get intraday data for
+   * @param params.interval - Time interval: '1min', '5min', '15min', '30min', '1hour', or '4hour'
+   * @param params.from - Start date in YYYY-MM-DD format (optional)
+   * @param params.to - End date in YYYY-MM-DD format (optional)
+   *
+   * @returns Promise resolving to intraday price data with OHLCV information at specified intervals
+   *
+   * @example
+   * ```typescript
+   * // Get 5-minute intraday data for today
+   * const intraday = await fmp.quote.getIntraday({
+   *   symbol: 'AAPL',
+   *   interval: '5min',
+   *   from: '2024-01-15'
+   * });
+   *
+   * // Get 1-hour data for crypto
+   * const cryptoIntraday = await fmp.quote.getIntraday({
+   *   symbol: 'BTCUSD',
+   *   interval: '1hour',
+   *   from: '2024-01-10',
+   *   to: '2024-01-15'
+   * });
+   * ```
    */
   async getIntraday(params) {
     const { symbol, interval, from, to } = params;
@@ -1064,56 +2331,202 @@ var SenateHouseEndpoints = class {
     this.client = client;
   }
   /**
-   * Get senate trading data only
-   * https://site.financialmodelingprep.com/developer/docs#senate-trading
-   * @param symbol - The stock symbol to get the senate trading data for
-   * @returns Senate trading data only
+   * Get senate trading data for a specific stock symbol
+   *
+   * Provides detailed information about senate members' trading activities for a specific stock.
+   * Includes transaction details, amounts, dates, and ownership information for transparency
+   * and compliance with the STOCK Act (Stop Trading on Congressional Knowledge).
+   *
+   * @param params - Senate trading request parameters
+   * @param params.symbol - The stock symbol to get senate trading data for (e.g., 'AAPL', 'MSFT', 'TSLA')
+   *
+   * @returns Promise resolving to array of senate trading data with transaction details
+   *
+   * @example
+   * ```typescript
+   * // Get senate trading data for Apple
+   * const appleSenateTrading = await fmp.senateHouse.getSenateTrading({ symbol: 'AAPL' });
+   * appleSenateTrading.data.forEach(trade => {
+   *   console.log(`${trade.firstName} ${trade.lastName} (${trade.office}):`);
+   *   console.log(`  ${trade.type} ${trade.amount} of ${trade.assetDescription}`);
+   *   console.log(`  Transaction Date: ${trade.transactionDate}`);
+   * });
+   *
+   * // Get senate trading data for Tesla
+   * const teslaSenateTrading = await fmp.senateHouse.getSenateTrading({ symbol: 'TSLA' });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#senate-trading|FMP Senate Trading Documentation}
    */
   async getSenateTrading(params) {
     const { symbol } = params;
     return this.client.get(`/senate-trading`, "v4", { symbol });
   }
-  /** Get senate trading RSS feed
-   * https://site.financialmodelingprep.com/developer/docs#senate-trading-rss-feed-senate
-   * @param page - The page number to get
-   * @returns Senate trading RSS feed
+  /**
+   * Get senate trading RSS feed with pagination
+   *
+   * Provides a paginated RSS feed of all senate trading activities across all stocks.
+   * Useful for monitoring congressional trading activities, compliance tracking,
+   * and transparency reporting. Returns recent trading disclosures from senate members.
+   *
+   * @param params - Senate trading RSS feed request parameters
+   * @param params.page - The page number to retrieve (starts from 0)
+   *
+   * @returns Promise resolving to array of senate trading data from RSS feed
+   *
+   * @example
+   * ```typescript
+   * // Get first page of senate trading RSS feed
+   * const firstPage = await fmp.senateHouse.getSenateTradingRSSFeed({ page: 0 });
+   * console.log(`First page: ${firstPage.data.length} trading activities`);
+   *
+   * // Get second page of senate trading RSS feed
+   * const secondPage = await fmp.senateHouse.getSenateTradingRSSFeed({ page: 1 });
+   * console.log(`Second page: ${secondPage.data.length} trading activities`);
+   *
+   * // Get recent senate trading activities
+   * const recentTrades = await fmp.senateHouse.getSenateTradingRSSFeed({ page: 0 });
+   * recentTrades.data.forEach(trade => {
+   *   console.log(`${trade.firstName} ${trade.lastName}: ${trade.type} ${trade.amount}`);
+   * });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#senate-trading-rss-feed-senate|FMP Senate Trading RSS Feed Documentation}
    */
   async getSenateTradingRSSFeed(params) {
     const { page } = params;
     return this.client.get("/senate-trading-rss-feed", "v4", { page });
   }
-  /** Get Senate trades by name
-   * https://site.financialmodelingprep.com/developer/docs/stable#senate-trading-by-name
-   * @param name - The name of the senator to get the trades for
-   * @returns Senate trades by name
+  /**
+   * Get senate trading data for a specific senator by name
+   *
+   * Provides detailed trading activities for a specific senate member across all stocks.
+   * Useful for tracking individual senator's trading patterns, compliance monitoring,
+   * and transparency reporting. Returns all trading disclosures for the specified senator.
+   *
+   * @param params - Senate trading by name request parameters
+   * @param params.name - The name of the senator to get trading data for (e.g., 'John Smith', 'Jane Doe')
+   *
+   * @returns Promise resolving to array of senate trading data for the specified senator
+   *
+   * @example
+   * ```typescript
+   * // Get trading data for Senator John Smith
+   * const johnSmithTrades = await fmp.senateHouse.getSenateTradingByName({ name: 'John Smith' });
+   * johnSmithTrades.data.forEach(trade => {
+   *   console.log(`${trade.symbol}: ${trade.type} ${trade.amount}`);
+   *   console.log(`  Transaction Date: ${trade.transactionDate}`);
+   *   console.log(`  Asset: ${trade.assetDescription}`);
+   * });
+   *
+   * // Get trading data for Senator Jane Doe
+   * const janeDoeTrades = await fmp.senateHouse.getSenateTradingByName({ name: 'Jane Doe' });
+   * console.log(`Jane Doe has ${janeDoeTrades.data.length} trading activities`);
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs/stable#senate-trading-by-name|FMP Senate Trading by Name Documentation}
    */
   async getSenateTradingByName(params) {
     const { name } = params;
     return this.client.get("/senate-trades-by-name", "stable", { name });
   }
   /**
-   * Get house trading data only
-   * https://site.financialmodelingprep.com/developer/docs#house-disclosure
-   * @param symbol - The stock symbol to get the house trading data for
-   * @returns House trading data only
+   * Get house trading data for a specific stock symbol
+   *
+   * Provides detailed information about house representatives' trading activities for a specific stock.
+   * Includes transaction details, amounts, dates, and district information for transparency
+   * and compliance with the STOCK Act (Stop Trading on Congressional Knowledge).
+   *
+   * @param params - House trading request parameters
+   * @param params.symbol - The stock symbol to get house trading data for (e.g., 'AAPL', 'MSFT', 'TSLA')
+   *
+   * @returns Promise resolving to array of house trading data with transaction details
+   *
+   * @example
+   * ```typescript
+   * // Get house trading data for Apple
+   * const appleHouseTrading = await fmp.senateHouse.getHouseTrading({ symbol: 'AAPL' });
+   * appleHouseTrading.data.forEach(trade => {
+   *   console.log(`${trade.representative} (District ${trade.district}):`);
+   *   console.log(`  ${trade.type} ${trade.amount} of ${trade.assetDescription}`);
+   *   console.log(`  Transaction Date: ${trade.transactionDate}`);
+   * });
+   *
+   * // Get house trading data for Microsoft
+   * const msftHouseTrading = await fmp.senateHouse.getHouseTrading({ symbol: 'MSFT' });
+   * console.log(`Microsoft house trading activities: ${msftHouseTrading.data.length}`);
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#house-disclosure|FMP House Trading Documentation}
    */
   async getHouseTrading(params) {
     const { symbol } = params;
     return this.client.get("/senate-disclosure", "v4", { symbol });
   }
-  /** Get house trading RSS feed
-   * https://site.financialmodelingprep.com/developer/docs#house-disclosure-rss-feed-senate
-   * @param page - The page number to get
-   * @returns House trading RSS feed
+  /**
+   * Get house trading RSS feed with pagination
+   *
+   * Provides a paginated RSS feed of all house trading activities across all stocks.
+   * Useful for monitoring congressional trading activities, compliance tracking,
+   * and transparency reporting. Returns recent trading disclosures from house representatives.
+   *
+   * @param params - House trading RSS feed request parameters
+   * @param params.page - The page number to retrieve (starts from 0)
+   *
+   * @returns Promise resolving to array of house trading data from RSS feed
+   *
+   * @example
+   * ```typescript
+   * // Get first page of house trading RSS feed
+   * const firstPage = await fmp.senateHouse.getHouseTradingRSSFeed({ page: 0 });
+   * console.log(`First page: ${firstPage.data.length} trading activities`);
+   *
+   * // Get second page of house trading RSS feed
+   * const secondPage = await fmp.senateHouse.getHouseTradingRSSFeed({ page: 1 });
+   * console.log(`Second page: ${secondPage.data.length} trading activities`);
+   *
+   * // Get recent house trading activities
+   * const recentTrades = await fmp.senateHouse.getHouseTradingRSSFeed({ page: 0 });
+   * recentTrades.data.forEach(trade => {
+   *   console.log(`${trade.representative} (District ${trade.district}): ${trade.type} ${trade.amount}`);
+   * });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#house-disclosure-rss-feed-senate|FMP House Trading RSS Feed Documentation}
    */
   async getHouseTradingRSSFeed(params) {
     const { page } = params;
     return this.client.get("/senate-disclosure-rss-feed", "v4", { page });
   }
-  /** Get house trading by name
-   * https://site.financialmodelingprep.com/developer/docs/stable#house-trading-by-name
-   * @param name - The name of the representative to get the trades for
-   * @returns House trading by name
+  /**
+   * Get house trading data for a specific representative by name
+   *
+   * Provides detailed trading activities for a specific house representative across all stocks.
+   * Useful for tracking individual representative's trading patterns, compliance monitoring,
+   * and transparency reporting. Returns all trading disclosures for the specified representative.
+   *
+   * @param params - House trading by name request parameters
+   * @param params.name - The name of the representative to get trading data for (e.g., 'John Smith', 'Jane Doe')
+   *
+   * @returns Promise resolving to array of house trading data for the specified representative
+   *
+   * @example
+   * ```typescript
+   * // Get trading data for Representative John Smith
+   * const johnSmithTrades = await fmp.senateHouse.getHouseTradingByName({ name: 'John Smith' });
+   * johnSmithTrades.data.forEach(trade => {
+   *   console.log(`${trade.symbol}: ${trade.type} ${trade.amount}`);
+   *   console.log(`  Transaction Date: ${trade.transactionDate}`);
+   *   console.log(`  Asset: ${trade.assetDescription}`);
+   *   console.log(`  District: ${trade.district}`);
+   * });
+   *
+   * // Get trading data for Representative Jane Doe
+   * const janeDoeTrades = await fmp.senateHouse.getHouseTradingByName({ name: 'Jane Doe' });
+   * console.log(`Jane Doe has ${janeDoeTrades.data.length} trading activities`);
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs/stable#house-trading-by-name|FMP House Trading by Name Documentation}
    */
   async getHouseTradingByName(params) {
     const { name } = params;
@@ -1128,10 +2541,40 @@ var InstitutionalEndpoints = class {
   }
   /**
    * Get Form 13F institutional stock ownership data
-   * https://site.financialmodelingprep.com/developer/docs#form-13f-13f---institutional-stock-ownership
-   * @param symbol - The stock symbol to get the Form 13F data for
-   * @param date - The date to get the Form 13F data for (optional)
-   * @returns Form 13F institutional stock ownership data
+   *
+   * Provides Form 13F institutional stock ownership data for investment
+   * managers with over $100 million in assets under management. Essential
+   * for analyzing institutional investment patterns and holdings.
+   *
+   * @param params - Form 13F request parameters
+   * @param params.cik - Central Index Key (CIK) of the investment manager
+   * @param params.date - Specific date in YYYY-MM-DD format (optional, defaults to most recent filing)
+   *
+   * @returns Promise resolving to array of Form 13F institutional ownership data
+   *
+   * @example
+   * ```typescript
+   * // Get Berkshire Hathaway's Form 13F data
+   * const berkshire13F = await fmp.institutional.getForm13F({
+   *   cik: '0001067983'
+   * });
+   * berkshire13F.data.forEach(holding => {
+   *   console.log(`${holding.issuerName}: ${holding.value.toLocaleString()} shares, $${holding.value.toLocaleString()}`);
+   * });
+   *
+   * // Get Form 13F data for specific date
+   * const historical13F = await fmp.institutional.getForm13F({
+   *   cik: '0001067983',
+   *   date: '2023-12-31'
+   * });
+   *
+   * // Get BlackRock's Form 13F data
+   * const blackrock13F = await fmp.institutional.getForm13F({
+   *   cik: '0001364742'
+   * });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#form-13f-13f---institutional-stock-ownership|FMP Form 13F Documentation}
    */
   async getForm13F(params) {
     const { cik, date } = params;
@@ -1140,20 +2583,73 @@ var InstitutionalEndpoints = class {
     return this.client.get(`/form-thirteen/${cik}`, "v3", queryParams);
   }
   /**
-   * Get Form 13F dates for institutional stock ownership
-   * https://site.financialmodelingprep.com/developer/docs#form-13f-dates-13f---institutional-stock-ownership
-   * @param symbol - The stock symbol to get the Form 13F dates for
-   * @returns Form 13F dates for institutional stock ownership
+   * Get Form 13F filing dates for an investment manager
+   *
+   * Provides available filing dates for Form 13F submissions by a specific
+   * investment manager. Essential for discovering historical filing dates
+   * before requesting detailed Form 13F data.
+   *
+   * @param params - Form 13F dates request parameters
+   * @param params.cik - Central Index Key (CIK) of the investment manager
+   *
+   * @returns Promise resolving to array of available Form 13F filing dates
+   *
+   * @example
+   * ```typescript
+   * // Get Berkshire Hathaway's Form 13F filing dates
+   * const berkshireDates = await fmp.institutional.getForm13FDates({
+   *   cik: '0001067983'
+   * });
+   * berkshireDates.data.forEach(date => {
+   *   console.log(`Filing date: ${date}`);
+   * });
+   *
+   * // Get BlackRock's filing dates
+   * const blackrockDates = await fmp.institutional.getForm13FDates({
+   *   cik: '0001364742'
+   * });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#form-13f-dates-13f---institutional-stock-ownership|FMP Form 13F Dates Documentation}
    */
   async getForm13FDates(params) {
     const { cik } = params;
     return this.client.get(`/form-thirteen-date/${cik}`, "v3");
   }
   /**
-   * Get institutional holders data
-   * https://site.financialmodelingprep.com/developer/docs#institutional-holder-13f---institutional-stock-ownership
-   * @param symbol - The stock symbol to get the institutional holders for
-   * @returns Institutional holders data
+   * Get institutional holders for a company
+   *
+   * Provides data on institutional investors holding shares in a specific
+   * company. Essential for understanding institutional ownership patterns,
+   * major shareholders, and investment sentiment.
+   *
+   * @param params - Institutional holders request parameters
+   * @param params.symbol - Stock symbol to get institutional holders for
+   *
+   * @returns Promise resolving to array of institutional holders data
+   *
+   * @example
+   * ```typescript
+   * // Get Apple's institutional holders
+   * const appleHolders = await fmp.institutional.getInstitutionalHolders({
+   *   symbol: 'AAPL'
+   * });
+   * appleHolders.data.forEach(holder => {
+   *   console.log(`${holder.holder}: ${holder.shares.toLocaleString()} shares (${holder.weight}%)`);
+   * });
+   *
+   * // Get Microsoft's institutional holders
+   * const msftHolders = await fmp.institutional.getInstitutionalHolders({
+   *   symbol: 'MSFT'
+   * });
+   *
+   * // Get Tesla's institutional holders
+   * const teslaHolders = await fmp.institutional.getInstitutionalHolders({
+   *   symbol: 'TSLA'
+   * });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#institutional-holder-13f---institutional-stock-ownership|FMP Institutional Holders Documentation}
    */
   async getInstitutionalHolders(params) {
     const { symbol } = params;
@@ -1167,121 +2663,331 @@ var InsiderEndpoints = class {
     this.client = client;
   }
   /**
-   * Get insider trading RSS feed
-   * https://site.financialmodelingprep.com/developer/docs#insider-trades-rss-insider-trading
-   * @param params - Parameters for the RSS feed request
-   * @returns An RSS feed of insider trades, updated in real time
+   * Get insider trading RSS feed data
+   *
+   * Provides real-time RSS feed of insider trading activities across all
+   * publicly traded companies. Essential for monitoring insider trading
+   * patterns, corporate governance, and potential market-moving events.
+   *
+   * @param params - RSS feed request parameters
+   * @param params.page - Page number for pagination (default: 0)
+   *
+   * @returns Promise resolving to array of insider trading RSS feed data
+   *
+   * @example
+   * ```typescript
+   * // Get first page of insider trading RSS feed
+   * const rssFeed = await fmp.insider.getInsiderTradingRSS({ page: 0 });
+   * rssFeed.data.forEach(trade => {
+   *   console.log(`${trade.date}: ${trade.symbol} - ${trade.insiderName} ${trade.transactionType}`);
+   * });
+   *
+   * // Get second page of RSS feed
+   * const nextPage = await fmp.insider.getInsiderTradingRSS({ page: 1 });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#insider-trades-rss-insider-trading|FMP Insider Trading RSS Documentation}
    */
-  async getInsiderTradingRSS({
-    page
-  }) {
+  async getInsiderTradingRSS(params) {
+    const { page = 0 } = params;
     return this.client.get(`/insider-trading-rss-feed`, "v4", { page });
   }
   /**
-   * Search for insider trades
-   * https://site.financialmodelingprep.com/developer/docs#insider-trades-search-insider-trading
-   * @param params - Parameters for the insider trading search
-   * @returns A list of insider trades filtered by the provided parameters
+   * Search for insider trades with advanced filtering
+   *
+   * Provides comprehensive insider trading data with multiple filtering options
+   * including symbol, CIK numbers, and transaction types. Essential for detailed
+   * analysis of insider trading patterns and corporate governance.
+   *
+   * @param params - Insider trading search parameters
+   * @param params.symbol - Stock symbol to filter by (optional)
+   * @param params.reportingCik - Reporting CIK to filter by (optional)
+   * @param params.companyCik - Company CIK to filter by (optional)
+   * @param params.transactionType - Transaction type to filter by (optional)
+   * @param params.page - Page number for pagination (default: 0)
+   *
+   * @returns Promise resolving to array of insider trading search results
+   *
+   * @example
+   * ```typescript
+   * // Search for Apple insider trades
+   * const appleTrades = await fmp.insider.searchInsiderTrading({
+   *   symbol: 'AAPL',
+   *   page: 0
+   * });
+   * appleTrades.data.forEach(trade => {
+   *   console.log(`${trade.date}: ${trade.insiderName} - ${trade.transactionType} ${trade.sharesTraded} shares`);
+   * });
+   *
+   * // Search by transaction type
+   * const purchases = await fmp.insider.searchInsiderTrading({
+   *   transactionType: 'P-Purchase',
+   *   page: 0
+   * });
+   *
+   * // Search by CIK
+   * const cikTrades = await fmp.insider.searchInsiderTrading({
+   *   companyCik: '0000320193',
+   *   page: 0
+   * });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#insider-trades-search-insider-trading|FMP Insider Trading Search Documentation}
    */
-  async searchInsiderTrading({
-    symbol,
-    reportingCik,
-    companyCik,
-    transactionType,
-    page
-  }) {
-    const params = { page };
-    if (symbol) params.symbol = symbol;
-    if (reportingCik) params.reportingCik = reportingCik;
-    if (companyCik) params.companyCik = companyCik;
-    if (transactionType) params.transactionType = transactionType;
-    return this.client.get(`/insider-trading`, "v4", params);
+  async searchInsiderTrading(params) {
+    const { symbol, reportingCik, companyCik, transactionType, page = 0 } = params;
+    const queryParams = { page };
+    if (symbol) queryParams.symbol = symbol;
+    if (reportingCik) queryParams.reportingCik = reportingCik;
+    if (companyCik) queryParams.companyCik = companyCik;
+    if (transactionType) queryParams.transactionType = transactionType;
+    return this.client.get(`/insider-trading`, "v4", queryParams);
   }
   /**
-   * Get transaction types
-   * https://site.financialmodelingprep.com/developer/docs#transaction-types-insider-trading
-   * @returns A list of all insider transaction types
+   * Get all available transaction types
+   *
+   * Provides a comprehensive list of all insider trading transaction types
+   * used in SEC filings. Essential for understanding different types of
+   * insider trading activities and filtering search results.
+   *
+   * @returns Promise resolving to array of transaction types with descriptions
+   *
+   * @example
+   * ```typescript
+   * // Get all transaction types
+   * const transactionTypes = await fmp.insider.getTransactionTypes();
+   * transactionTypes.data.forEach(type => {
+   *   console.log(`${type.code}: ${type.description}`);
+   * });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#transaction-types-insider-trading|FMP Transaction Types Documentation}
    */
   async getTransactionTypes() {
     return this.client.get(`/insider-trading-transaction-type`, "v4");
   }
   /**
-   * Get insiders by symbol
-   * https://site.financialmodelingprep.com/developer/docs#insiders-by-symbol-insider-trading
-   * @param params - Parameters for the insiders request
-   * @returns A list of insiders for a specific company
+   * Get insiders roster for a specific company
+   *
+   * Provides a list of all insiders (officers, directors, and beneficial owners)
+   * for a specific company. Essential for understanding corporate governance
+   * structure and identifying key personnel.
+   *
+   * @param params - Insiders request parameters
+   * @param params.symbol - Stock symbol to get insiders for
+   *
+   * @returns Promise resolving to array of insiders data for the company
+   *
+   * @example
+   * ```typescript
+   * // Get Apple's insiders roster
+   * const appleInsiders = await fmp.insider.getInsidersBySymbol({ symbol: 'AAPL' });
+   * appleInsiders.data.forEach(insider => {
+   *   console.log(`${insider.name} - ${insider.title} (${insider.cik})`);
+   * });
+   *
+   * // Get Microsoft's insiders
+   * const msftInsiders = await fmp.insider.getInsidersBySymbol({ symbol: 'MSFT' });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#insiders-by-symbol-insider-trading|FMP Insiders by Symbol Documentation}
    */
-  async getInsidersBySymbol({
-    symbol
-  }) {
+  async getInsidersBySymbol(params) {
+    const { symbol } = params;
     return this.client.get(`/insider-roaster`, "v4", { symbol });
   }
   /**
-   * Get insider trade statistics
-   * https://site.financialmodelingprep.com/developer/docs#insider-trade-statistics-insider-trading
-   * @param params - Parameters for the statistics request
-   * @returns Statistics on insider trading activity for a specific company
+   * Get insider trade statistics for a company
+   *
+   * Provides comprehensive statistics on insider trading activity for a
+   * specific company including total trades, volume, and value metrics.
+   * Essential for analyzing insider trading patterns and sentiment.
+   *
+   * @param params - Statistics request parameters
+   * @param params.symbol - Stock symbol to get statistics for
+   *
+   * @returns Promise resolving to array of insider trade statistics data
+   *
+   * @example
+   * ```typescript
+   * // Get Apple's insider trade statistics
+   * const appleStats = await fmp.insider.getInsiderTradeStatistics({ symbol: 'AAPL' });
+   * appleStats.data.forEach(stat => {
+   *   console.log(`${stat.insiderName}: ${stat.totalTrades} trades, ${stat.totalShares} shares`);
+   * });
+   *
+   * // Get Microsoft's statistics
+   * const msftStats = await fmp.insider.getInsiderTradeStatistics({ symbol: 'MSFT' });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#insider-trade-statistics-insider-trading|FMP Insider Trade Statistics Documentation}
    */
-  async getInsiderTradeStatistics({
-    symbol
-  }) {
+  async getInsiderTradeStatistics(params) {
+    const { symbol } = params;
     return this.client.get(`/insider-roaster-statistic`, "v4", { symbol });
   }
   /**
-   * Get CIK mapper
-   * https://site.financialmodelingprep.com/developer/docs#cik-mapper-insider-trading
-   * @param params - Parameters for the CIK mapper request
-   * @returns A list of CIK numbers and corresponding company names
+   * Get CIK mapper data
+   *
+   * Provides a mapping between CIK (Central Index Key) numbers and company
+   * names. Essential for converting between CIK numbers and company
+   * identifiers in insider trading analysis.
+   *
+   * @param params - CIK mapper request parameters
+   * @param params.page - Page number for pagination (default: 0)
+   *
+   * @returns Promise resolving to array of CIK mapper data
+   *
+   * @example
+   * ```typescript
+   * // Get first page of CIK mapper
+   * const cikMapper = await fmp.insider.getCikMapper({ page: 0 });
+   * cikMapper.data.forEach(mapping => {
+   *   console.log(`CIK: ${mapping.cik} - Company: ${mapping.name}`);
+   * });
+   *
+   * // Get second page
+   * const nextPage = await fmp.insider.getCikMapper({ page: 1 });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#cik-mapper-insider-trading|FMP CIK Mapper Documentation}
    */
-  async getCikMapper({ page }) {
+  async getCikMapper(params) {
+    const { page = 0 } = params;
     return this.client.get(`/mapper-cik-name`, "v4", { page });
   }
   /**
-   * Get CIK mapper by name
-   * https://site.financialmodelingprep.com/developer/docs#cik-mapper-by-name-insider-trading
-   * @param params - Parameters for the CIK mapper by name request
-   * @returns A list of CIK numbers and corresponding names matching the search term
+   * Get CIK mapper by name search
+   *
+   * Provides CIK numbers and company names matching a search term.
+   * Useful for finding companies by partial name matches and
+   * converting company names to CIK numbers.
+   *
+   * @param params - CIK mapper by name request parameters
+   * @param params.name - Company name or partial name to search for
+   * @param params.page - Page number for pagination (default: 0)
+   *
+   * @returns Promise resolving to array of CIK mapper data matching the search
+   *
+   * @example
+   * ```typescript
+   * // Search for Apple by name
+   * const appleCik = await fmp.insider.getCikMapperByName({
+   *   name: 'Apple',
+   *   page: 0
+   * });
+   * appleCik.data.forEach(mapping => {
+   *   console.log(`CIK: ${mapping.cik} - Company: ${mapping.name}`);
+   * });
+   *
+   * // Search for Microsoft
+   * const msftCik = await fmp.insider.getCikMapperByName({
+   *   name: 'Microsoft',
+   *   page: 0
+   * });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#cik-mapper-by-name-insider-trading|FMP CIK Mapper by Name Documentation}
    */
-  async getCikMapperByName({
-    name,
-    page = 0
-  }) {
+  async getCikMapperByName(params) {
+    const { name, page = 0 } = params;
     return this.client.get(`/mapper-cik-name`, "v4", { name, page });
   }
   /**
    * Get CIK mapper by symbol
-   * https://site.financialmodelingprep.com/developer/docs#cik-mapper-company-insider-trading
-   * @param params - Parameters for the CIK mapper by symbol request
-   * @returns CIK number and corresponding company name for a specific symbol
+   *
+   * Provides CIK number and company name for a specific stock symbol.
+   * Essential for converting stock symbols to CIK numbers for use
+   * in insider trading searches and analysis.
+   *
+   * @param params - CIK mapper by symbol request parameters
+   * @param params.symbol - Stock symbol to get CIK for
+   *
+   * @returns Promise resolving to CIK mapper data for the symbol
+   *
+   * @example
+   * ```typescript
+   * // Get Apple's CIK by symbol
+   * const appleCik = await fmp.insider.getCikMapperBySymbol({ symbol: 'AAPL' });
+   * console.log(`Apple CIK: ${appleCik.data.cik} - ${appleCik.data.name}`);
+   *
+   * // Get Microsoft's CIK
+   * const msftCik = await fmp.insider.getCikMapperBySymbol({ symbol: 'MSFT' });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#cik-mapper-company-insider-trading|FMP CIK Mapper by Symbol Documentation}
    */
-  async getCikMapperBySymbol({
-    symbol
-  }) {
+  async getCikMapperBySymbol(params) {
+    const { symbol } = params;
     return this.client.getSingle(`/mapper-cik-company/${symbol}`, "v4");
   }
   /**
    * Get beneficial ownership acquisitions
-   * https://site.financialmodelingprep.com/developer/docs#acquisition-of-beneficial-ownership
-   * @param params - Parameters for the beneficial ownership request
-   * @returns A list of acquisitions of beneficial ownership for a specific company
+   *
+   * Provides data on acquisitions of beneficial ownership for a specific
+   * company. Essential for tracking significant ownership changes and
+   * corporate governance events.
+   *
+   * @param params - Beneficial ownership request parameters
+   * @param params.symbol - Stock symbol to get beneficial ownership data for
+   *
+   * @returns Promise resolving to array of beneficial ownership acquisition data
+   *
+   * @example
+   * ```typescript
+   * // Get Apple's beneficial ownership acquisitions
+   * const appleOwnership = await fmp.insider.getBeneficialOwnership({ symbol: 'AAPL' });
+   * appleOwnership.data.forEach(acquisition => {
+   *   console.log(`${acquisition.date}: ${acquisition.insiderName} acquired ${acquisition.sharesAcquired} shares`);
+   * });
+   *
+   * // Get Microsoft's beneficial ownership
+   * const msftOwnership = await fmp.insider.getBeneficialOwnership({ symbol: 'MSFT' });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#acquisition-of-beneficial-ownership|FMP Beneficial Ownership Documentation}
    */
-  async getBeneficialOwnership({
-    symbol
-  }) {
+  async getBeneficialOwnership(params) {
+    const { symbol } = params;
     return this.client.get(`/insider/ownership/acquisition_of_beneficial_ownership`, "v4", {
       symbol
     });
   }
   /**
    * Get fail to deliver data
-   * https://site.financialmodelingprep.com/developer/docs#fail-to-deliver
-   * @param params - Parameters for the fail to deliver request
-   * @returns A list of fail to deliver data for a specific company
+   *
+   * Provides fail to deliver data for a specific company, which indicates
+   * when market participants fail to deliver securities on settlement date.
+   * Important for understanding market mechanics and potential short interest.
+   *
+   * @param params - Fail to deliver request parameters
+   * @param params.symbol - Stock symbol to get fail to deliver data for
+   * @param params.page - Page number for pagination (default: 0)
+   *
+   * @returns Promise resolving to array of fail to deliver data
+   *
+   * @example
+   * ```typescript
+   * // Get Apple's fail to deliver data
+   * const appleFailToDeliver = await fmp.insider.getFailToDeliver({
+   *   symbol: 'AAPL',
+   *   page: 0
+   * });
+   * appleFailToDeliver.data.forEach(entry => {
+   *   console.log(`${entry.date}: ${entry.shares} shares failed to deliver`);
+   * });
+   *
+   * // Get Microsoft's fail to deliver data
+   * const msftFailToDeliver = await fmp.insider.getFailToDeliver({
+   *   symbol: 'MSFT',
+   *   page: 0
+   * });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#fail-to-deliver|FMP Fail to Deliver Documentation}
    */
-  async getFailToDeliver({
-    symbol,
-    page = 0
-  }) {
+  async getFailToDeliver(params) {
+    const { symbol, page = 0 } = params;
     return this.client.get(`/fail_to_deliver`, "v4", { symbol, page });
   }
   /**
@@ -1329,46 +3035,167 @@ var SECEndpoints = class {
   }
   /**
    * Get RSS feed of SEC filings
-   * https://site.financialmodelingprep.com/developer/docs#rss-feed-securities-and-exchange-commission-(s.e.c)
-   * @param params - RSS feed parameters
-   * @returns A real-time feed of SEC filings from publicly traded companies, including the filing type, link to SEC page, and direct link to the filing. This endpoint can be used to stay up-to-date on the latest SEC filings for all companies or for a specific set of companies.
+   *
+   * Provides a real-time feed of SEC filings from publicly traded companies,
+   * including filing types, links to SEC pages, and direct links to filings.
+   * Essential for staying up-to-date on the latest SEC filings for all companies
+   * or for monitoring specific companies' regulatory activities.
+   *
+   * @param params - RSS feed parameters (optional)
+   * @returns Promise resolving to array of RSS feed items with SEC filing information
+   *
+   * @example
+   * ```typescript
+   * // Get all recent SEC filings
+   * const allFilings = await fmp.sec.getRSSFeed();
+   * console.log(`Recent SEC filings: ${allFilings.data.length}`);
+   *
+   * // Get specific filing type
+   * const form4Filings = await fmp.sec.getRSSFeed({ type: '4' });
+   * console.log(`Form 4 filings: ${form4Filings.data.length}`);
+   *
+   * // Get filings with date range
+   * const recentFilings = await fmp.sec.getRSSFeed({
+   *   from: '2024-01-01',
+   *   to: '2024-01-31'
+   * });
+   * console.log(`Recent filings: ${recentFilings.data.length}`);
+   *
+   * // Get limited results
+   * const limitedFilings = await fmp.sec.getRSSFeed({ limit: 10 });
+   * console.log(`Limited filings: ${limitedFilings.data.length}`);
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#rss-feed-securities-and-exchange-commission-(s.e.c)|FMP RSS Feed Documentation}
    */
   async getRSSFeed(params) {
     return this.client.get("/rss_feed", "v4", params);
   }
   /**
-   * Get RSS feed of all SEC filings
-   * https://site.financialmodelingprep.com/developer/docs#rss-feed-all-securities-and-exchange-commission-(s.e.c)
-   * @param params - RSS feed all parameters
-   * @returns A real-time feed of all SEC filings from publicly traded companies in the latest RSS feed format. This endpoint provides a comprehensive overview of all SEC filings, including the filing type, link to SEC page, and direct link to the filing.
+   * Get comprehensive RSS feed of all SEC filings
+   *
+   * Provides a comprehensive real-time feed of all SEC filings from publicly
+   * traded companies in the latest RSS feed format. This endpoint offers the
+   * most complete overview of SEC filings with enhanced metadata and formatting.
+   *
+   * @param params - RSS feed all parameters (optional)
+   * @returns Promise resolving to array of comprehensive RSS feed items with enhanced SEC filing information
+   *
+   * @example
+   * ```typescript
+   * // Get all comprehensive SEC filings
+   * const allFilings = await fmp.sec.getRSSFeedAll();
+   * console.log(`Comprehensive SEC filings: ${allFilings.data.length}`);
+   *
+   * // Get paginated results
+   * const page2Filings = await fmp.sec.getRSSFeedAll({ page: 1 });
+   * console.log(`Page 2 filings: ${page2Filings.data.length}`);
+   *
+   * // Get specific data type
+   * const specificData = await fmp.sec.getRSSFeedAll({ datatype: 'json' });
+   * console.log(`Specific data type filings: ${specificData.data.length}`);
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#rss-feed-all-securities-and-exchange-commission-(s.e.c)|FMP RSS Feed All Documentation}
    */
   async getRSSFeedAll(params) {
     return this.client.get("/rss_feed_all", "v4", params);
   }
   /**
    * Get RSS feed V3 of SEC filings
-   * https://site.financialmodelingprep.com/developer/docs#rss-feed-v3-securities-and-exchange-commission-(s.e.c)
-   * @param params - RSS feed V3 parameters
-   * @returns A real-time feed of SEC filings from publicly traded companies in the latest RSS feed format (V3)
+   *
+   * Provides a real-time feed of SEC filings from publicly traded companies
+   * in the V3 RSS feed format. This version offers enhanced metadata and
+   * improved structure for better parsing and analysis of SEC filings.
+   *
+   * @param params - RSS feed V3 parameters (optional)
+   * @returns Promise resolving to array of V3 RSS feed items with enhanced SEC filing information
+   *
+   * @example
+   * ```typescript
+   * // Get V3 format SEC filings
+   * const v3Filings = await fmp.sec.getRSSFeedV3();
+   * console.log(`V3 SEC filings: ${v3Filings.data.length}`);
+   *
+   * // Get paginated V3 results
+   * const page2V3 = await fmp.sec.getRSSFeedV3({ page: 1 });
+   * console.log(`Page 2 V3 filings: ${page2V3.data.length}`);
+   *
+   * // Get specific data type
+   * const specificV3 = await fmp.sec.getRSSFeedV3({ datatype: 'json' });
+   * console.log(`Specific V3 data type: ${specificV3.data.length}`);
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#rss-feed-v3-securities-and-exchange-commission-(s.e.c)|FMP RSS Feed V3 Documentation}
    */
   async getRSSFeedV3(params) {
     return this.client.get("/rss_feed", "v3", params);
   }
   /**
    * Get RSS feed of 8-K SEC filings
-   * https://site.financialmodelingprep.com/developer/docs#rss-feed-8-k-securities-and-exchange-commission-(s.e.c)
-   * @param params - RSS feed 8-K parameters
-   * @returns A real-time feed of 8-K SEC filings from publicly traded companies
+   *
+   * Provides a real-time feed specifically for 8-K SEC filings from publicly
+   * traded companies. 8-K filings are used to announce major events that
+   * shareholders should know about, such as earnings releases, mergers,
+   * acquisitions, and other material events.
+   *
+   * @param params - RSS feed 8-K parameters (optional)
+   * @returns Promise resolving to array of 8-K RSS feed items with material event information
+   *
+   * @example
+   * ```typescript
+   * // Get all 8-K filings
+   * const form8KFilings = await fmp.sec.getRSSFeed8K();
+   * console.log(`8-K filings: ${form8KFilings.data.length}`);
+   *
+   * // Get 8-K filings with date range
+   * const recent8K = await fmp.sec.getRSSFeed8K({
+   *   from: '2024-01-01',
+   *   to: '2024-01-31'
+   * });
+   * console.log(`Recent 8-K filings: ${recent8K.data.length}`);
+   *
+   * // Get 8-K filings with financials
+   * const financial8K = await fmp.sec.getRSSFeed8K({ hasFinancial: true });
+   * console.log(`8-K filings with financials: ${financial8K.data.length}`);
+   *
+   * // Get limited 8-K results
+   * const limited8K = await fmp.sec.getRSSFeed8K({ limit: 10 });
+   * console.log(`Limited 8-K filings: ${limited8K.data.length}`);
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#rss-feed-8-k-securities-and-exchange-commission-(s.e.c)|FMP RSS Feed 8-K Documentation}
    */
   async getRSSFeed8K(params) {
     return this.client.get("/rss_feed_8k", "v4", params);
   }
   /**
    * Get SEC filings for a specific company
-   * https://site.financialmodelingprep.com/developer/docs#sec-filings-securities-and-exchange-commission-(s.e.c)
-   * @param symbol - The stock symbol to get SEC filings for
-   * @param params - SEC filings parameters
-   * @returns Access direct links to SEC filings, including the filing type, link to the SEC page, and direct link to the specific filing
+   *
+   * Provides direct access to SEC filings for a specific company, including
+   * filing types, links to SEC pages, and direct links to specific filings.
+   * Essential for monitoring a company's regulatory compliance and staying
+   * informed about important corporate events and disclosures.
+   *
+   * @param symbol - The stock symbol to get SEC filings for (e.g., 'AAPL', 'MSFT', 'GOOGL')
+   * @param params - SEC filings parameters (optional)
+   * @returns Promise resolving to array of SEC filings with detailed filing information
+   *
+   * @example
+   * ```typescript
+   * // Get all SEC filings for Apple
+   * const appleFilings = await fmp.sec.getSECFilings({ symbol: 'AAPL' });
+   * console.log(`Apple SEC filings: ${appleFilings.data.length}`);
+   *
+   * // Get specific filing type for Microsoft
+   * const msftForm4 = await fmp.sec.getSECFilings({
+   *   symbol: 'MSFT',
+   *   params: { type: '4' }
+   * });
+   * console.log(`Microsoft Form 4 filings: ${msftForm4.data.length}`);
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#sec-filings-securities-and-exchange-commission-(s.e.c)|FMP SEC Filings Documentation}
    */
   async getSECFilings({
     symbol,
@@ -1377,42 +3204,177 @@ var SECEndpoints = class {
     return this.client.get(`/sec_filings/${symbol}`, "v3", params);
   }
   /**
-   * Get individual industry classification
-   * https://site.financialmodelingprep.com/developer/docs#individual-industry-classification-standard-industrial-classification
+   * Get individual industry classification for a company
+   *
+   * Provides the industry classification for a specific company based on the
+   * Standard Industrial Classification (SIC) system. Essential for understanding
+   * a company's business sector, industry peers, and market positioning.
+   *
    * @param params - Industry classification parameters
-   * @returns Identify the industry in which a particular company operates, based on the Standard Industrial Classification (SIC) system
+   * @returns Promise resolving to industry classification data with SIC code and description
+   *
+   * @example
+   * ```typescript
+   * // Get Apple's industry classification by symbol
+   * const appleIndustry = await fmp.sec.getIndividualIndustryClassification({ symbol: 'AAPL' });
+   * console.log(`Apple Industry: ${appleIndustry.data.industryTitle}`);
+   * console.log(`SIC Code: ${appleIndustry.data.sicCode}`);
+   *
+   * // Get industry classification by CIK
+   * const cikIndustry = await fmp.sec.getIndividualIndustryClassification({ cik: 320193 });
+   * console.log(`CIK Industry: ${cikIndustry.data.industryTitle}`);
+   *
+   * // Get industry classification by SIC code
+   * const sicIndustry = await fmp.sec.getIndividualIndustryClassification({ sicCode: 3571 });
+   * console.log(`SIC Industry: ${sicIndustry.data.industryTitle}`);
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#individual-industry-classification-standard-industrial-classification|FMP Individual Industry Classification Documentation}
    */
   async getIndividualIndustryClassification(params) {
     return this.client.getSingle("/standard_industrial_classification", "v4", params);
   }
   /**
    * Get all industry classifications
-   * https://site.financialmodelingprep.com/developer/docs#all-industry-classification-standard-industrial-classification
-   * @returns Get a comprehensive overview of all industries, classified according to the SIC system
+   *
+   * Provides a comprehensive overview of all industries classified according
+   * to the Standard Industrial Classification (SIC) system. Essential for
+   * understanding industry categories, sector analysis, and market research.
+   *
+   * @returns Promise resolving to array of all industry classifications with SIC codes and descriptions
+   *
+   * @example
+   * ```typescript
+   * // Get all industry classifications
+   * const allIndustries = await fmp.sec.getAllIndustryClassifications();
+   * console.log(`Total industries: ${allIndustries.data.length}`);
+   *
+   * allIndustries.data.forEach((industry, index) => {
+   *   console.log(`${index + 1}. ${industry.industryTitle}`);
+   *   console.log(`   SIC Code: ${industry.sicCode}`);
+   * });
+   *
+   * // Find specific industry
+   * const techIndustry = allIndustries.data.find(industry =>
+   *   industry.industryTitle.toLowerCase().includes('computer')
+   * );
+   * console.log(`Tech Industry: ${techIndustry?.industryTitle}`);
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#all-industry-classification-standard-industrial-classification|FMP All Industry Classifications Documentation}
    */
   async getAllIndustryClassifications() {
     return this.client.get("/standard_industrial_classification/all", "v4");
   }
   /**
    * Get industry classification codes
-   * https://site.financialmodelingprep.com/developer/docs#industry-classification-codes-standard-industrial-classification
+   *
+   * Provides detailed information about the Standard Industrial Classification
+   * (SIC) system and helps identify SIC codes for specific industries.
+   * Essential for understanding industry categorization and sector analysis.
+   *
    * @param params - Industry classification codes parameters
-   * @returns Learn more about the SIC system and identify the SIC code for a particular industry
+   * @returns Promise resolving to array of industry classification codes with detailed information
+   *
+   * @example
+   * ```typescript
+   * // Get all industry classification codes
+   * const allCodes = await fmp.sec.getIndustryClassificationCodes({});
+   * console.log(`Total SIC codes: ${allCodes.data.length}`);
+   *
+   * // Search for specific SIC code
+   * const code3571 = await fmp.sec.getIndustryClassificationCodes({ sicCode: 3571 });
+   * console.log(`SIC 3571: ${code3571.data[0]?.industryTitle}`);
+   *
+   * // Search for industry by title
+   * const computerIndustry = await fmp.sec.getIndustryClassificationCodes({ industryTitle: 'Computer' });
+   * console.log(`Computer-related industries: ${computerIndustry.data.length}`);
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#industry-classification-codes-standard-industrial-classification|FMP Industry Classification Codes Documentation}
    */
   async getIndustryClassificationCodes(params) {
     return this.client.get("/standard_industrial_classification_list", "v4", params);
   }
 };
 
+// src/endpoints/mutual-fund.ts
+var MutualFundEndpoints = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get mutual fund holders of a specific stock
+   *
+   * Provides data on mutual funds that hold shares in a specific stock.
+   * Essential for understanding mutual fund ownership patterns and
+   * which mutual funds are invested in particular companies.
+   *
+   * @param symbol - The stock symbol to get mutual fund holders for (e.g., 'AAPL', 'MSFT', 'GOOGL')
+   *
+   * @returns Promise resolving to array of mutual fund holders with position details
+   *
+   * @example
+   * ```typescript
+   * // Get mutual funds that hold Apple stock
+   * const appleHolders = await fmp.mutualFund.getHolders('AAPL');
+   * console.log(`${appleHolders.data.length} mutual funds hold AAPL`);
+   *
+   * appleHolders.data.forEach((holder, index) => {
+   *   console.log(`${index + 1}. ${holder.holder}`);
+   *   console.log(`   Shares: ${holder.shares?.toLocaleString() || 'N/A'}`);
+   *   console.log(`   Weight: ${holder.weightPercent}% | Change: ${holder.change}`);
+   * });
+   *
+   * // Get mutual funds that hold Microsoft stock
+   * const msftHolders = await fmp.mutualFund.getHolders('MSFT');
+   *
+   * // Find top mutual fund holders by shares
+   * const topHolders = msftHolders.data
+   *   .sort((a, b) => (b.shares || 0) - (a.shares || 0))
+   *   .slice(0, 10);
+   * console.log('Top 10 mutual fund holders by shares:');
+   * topHolders.forEach((holder, index) => {
+   *   console.log(`${index + 1}. ${holder.holder}: ${holder.shares.toLocaleString()} shares`);
+   * });
+   *
+   * // Get mutual funds that hold Google stock
+   * const googlHolders = await fmp.mutualFund.getHolders('GOOGL');
+   *
+   * // Analyze mutual fund concentration
+   * const totalShares = googlHolders.data.reduce((sum, holder) => sum + (holder.shares || 0), 0);
+   * console.log(`Total shares held by mutual funds: ${totalShares.toLocaleString()}`);
+   *
+   * googlHolders.data.forEach(holder => {
+   *   const percentage = ((holder.shares || 0) / totalShares * 100).toFixed(2);
+   *   console.log(`${holder.holder}: ${percentage}% of total mutual fund holdings`);
+   * });
+   * ```
+   *
+   * @see {@link https://site.financialmodelingprep.com/developer/docs#mutual-fund-holder-mutual-funds-holdings|FMP Mutual Fund Holders Documentation}
+   */
+  async getHolders(symbol) {
+    return this.client.get(`/mutual-fund-holder/${symbol}`, "v3");
+  }
+};
+
 // src/fmp.ts
 var FMP = class {
-  constructor(config) {
-    validateApiKey(config.apiKey);
-    const client = new FMPClient(config);
+  constructor(config = {}) {
+    const apiKey = config.apiKey || process.env.FMP_API_KEY;
+    if (!apiKey) {
+      throw new Error(
+        "FMP API key is required. Please provide it in the config or set the FMP_API_KEY environment variable."
+      );
+    }
+    if (!FMPValidation.isValidApiKey(apiKey)) {
+      throw new Error("Invalid API key format");
+    }
+    const client = new FMPClient({ ...config, apiKey });
     this.stock = new StockEndpoints(client);
     this.financial = new FinancialEndpoints(client);
-    this.crypto = new CryptoEndpoints(client);
     this.etf = new ETFEndpoints(client);
+    this.economic = new EconomicEndpoints(client);
     this.market = new MarketEndpoints(client);
     this.list = new ListEndpoints(client);
     this.calendar = new CalendarEndpoints(client);
@@ -1422,8 +3384,6 @@ var FMP = class {
     this.institutional = new InstitutionalEndpoints(client);
     this.insider = new InsiderEndpoints(client);
     this.sec = new SECEndpoints(client);
-    this.forex = new ForexEndpoints(client);
-    this.economic = new EconomicEndpoints(client);
     this.mutualFund = new MutualFundEndpoints(client);
   }
   /**
@@ -1475,58 +3435,6 @@ var TransactionType = /* @__PURE__ */ ((TransactionType2) => {
   return TransactionType2;
 })(TransactionType || {});
 
-// src/utils/formatting.ts
-function formatCurrency(value, currency = "USD") {
-  return new Intl.NumberFormat("en-US", {
-    style: "currency",
-    currency
-  }).format(value);
-}
-function formatPercentage(value, decimals = 2) {
-  return `${value.toFixed(decimals)}%`;
-}
-function formatLargeNumber(value) {
-  if (value >= 1e12) {
-    return `${(value / 1e12).toFixed(2)}T`;
-  } else if (value >= 1e9) {
-    return `${(value / 1e9).toFixed(2)}B`;
-  } else if (value >= 1e6) {
-    return `${(value / 1e6).toFixed(2)}M`;
-  } else if (value >= 1e3) {
-    return `${(value / 1e3).toFixed(2)}K`;
-  }
-  return value.toString();
-}
-function formatDate(date) {
-  const d = typeof date === "string" ? new Date(date) : date;
-  return d.toISOString().split("T")[0];
-}
-function formatReadableDate(date) {
-  const d = typeof date === "string" ? new Date(date) : date;
-  return d.toLocaleDateString("en-US", {
-    year: "numeric",
-    month: "long",
-    day: "numeric"
-  });
-}
-function formatTimestamp(timestamp) {
-  const date = new Date(timestamp * 1e3);
-  return date.toLocaleString("en-US");
-}
-function formatNumber(value, decimals = 2) {
-  return value.toFixed(decimals);
-}
-function formatVolume(volume) {
-  if (volume >= 1e9) {
-    return `${(volume / 1e9).toFixed(2)}B`;
-  } else if (volume >= 1e6) {
-    return `${(volume / 1e6).toFixed(2)}M`;
-  } else if (volume >= 1e3) {
-    return `${(volume / 1e3).toFixed(2)}K`;
-  }
-  return volume.toString();
-}
-
 // src/utils/constants.ts
 var DEFAULT_TIMEOUT = 1e4;
 var DEFAULT_LIMIT = 100;
@@ -1594,6 +3502,636 @@ var HTTP_STATUS = {
   INTERNAL_SERVER_ERROR: 500
 };
 
-export { COUNTRIES, CalendarEndpoints, CompanyEndpoints, CryptoEndpoints, DEFAULT_LIMIT, DEFAULT_TIMEOUT, ERROR_MESSAGES, ETFEndpoints, EXCHANGES, EconomicEndpoints, Exchange, FMP, FMPClient, FinancialEndpoints, ForexEndpoints, HTTP_STATUS, InsiderEndpoints, InstitutionalEndpoints, ListEndpoints, MAX_LIMIT, MarketEndpoints, MutualFundEndpoints, PERIODS, Period, QuoteEndpoints, SECEndpoints, SECTORS, SenateHouseEndpoints, StockEndpoints, TransactionType, formatCurrency, formatDate, formatLargeNumber, formatNumber, formatPercentage, formatReadableDate, formatTimestamp, formatVolume, validateApiKey, validateDate, validateLimit, validatePage, validatePeriod, validateSymbol };
+// src/utils/formatting.ts
+function formatCurrency(value, currency = "USD") {
+  return new Intl.NumberFormat("en-US", {
+    style: "currency",
+    currency
+  }).format(value);
+}
+function formatPercentage(value, decimals = 2) {
+  return `${value.toFixed(decimals)}%`;
+}
+function formatLargeNumber(value) {
+  if (value >= 1e12) {
+    return `${(value / 1e12).toFixed(2)}T`;
+  } else if (value >= 1e9) {
+    return `${(value / 1e9).toFixed(2)}B`;
+  } else if (value >= 1e6) {
+    return `${(value / 1e6).toFixed(2)}M`;
+  } else if (value >= 1e3) {
+    return `${(value / 1e3).toFixed(2)}K`;
+  }
+  return value.toString();
+}
+function formatDate(date) {
+  const d = typeof date === "string" ? new Date(date) : date;
+  return d.toISOString().split("T")[0];
+}
+function formatReadableDate(date) {
+  const d = typeof date === "string" ? new Date(date) : date;
+  return d.toLocaleDateString("en-US", {
+    year: "numeric",
+    month: "long",
+    day: "numeric"
+  });
+}
+function formatTimestamp(timestamp) {
+  const date = new Date(timestamp * 1e3);
+  return date.toLocaleString("en-US");
+}
+function formatNumber(value, decimals = 2) {
+  return value.toFixed(decimals);
+}
+function formatVolume(volume) {
+  if (volume >= 1e9) {
+    return `${(volume / 1e9).toFixed(2)}B`;
+  } else if (volume >= 1e6) {
+    return `${(volume / 1e6).toFixed(2)}M`;
+  } else if (volume >= 1e3) {
+    return `${(volume / 1e3).toFixed(2)}K`;
+  }
+  return volume.toString();
+}
+
+// src/utils/helpers.ts
+var FMPHelpers = class {
+  /**
+   * Get all available endpoint categories from the FMP client
+   * @param fmp - The FMP client instance
+   * @returns Array of endpoint category names
+   */
+  static getEndpointCategories(fmp) {
+    return Object.keys(fmp).filter(
+      (key) => typeof fmp[key] === "object" && fmp[key] !== null && key !== "constructor"
+    );
+  }
+  /**
+   * Get all methods for a specific endpoint category
+   * @param fmp - The FMP client instance
+   * @param endpoint - The endpoint category name
+   * @returns Array of method names
+   */
+  static getEndpointMethods(fmp, endpoint) {
+    const endpointObj = fmp[endpoint];
+    if (!endpointObj || typeof endpointObj !== "object") {
+      return [];
+    }
+    return Object.getOwnPropertyNames(endpointObj).filter(
+      (name) => typeof endpointObj[name] === "function" && name !== "constructor"
+    );
+  }
+  /**
+   * Get all available methods across all endpoint categories
+   * @param fmp - The FMP client instance
+   * @returns Object mapping endpoint categories to their methods
+   */
+  static getAllMethods(fmp) {
+    const methods = {};
+    const categories = this.getEndpointCategories(fmp);
+    categories.forEach((category) => {
+      methods[category] = this.getEndpointMethods(fmp, category);
+    });
+    return methods;
+  }
+  /**
+   * Get a summary of the API structure
+   * @param fmp - The FMP client instance
+   * @returns Summary object with endpoint and method counts
+   */
+  static getApiSummary(fmp) {
+    const categories = this.getEndpointCategories(fmp);
+    const allMethods = this.getAllMethods(fmp);
+    const totalMethods = Object.values(allMethods).reduce(
+      (sum, methods) => sum + methods.length,
+      0
+    );
+    const methodCounts = {};
+    categories.forEach((category) => {
+      methodCounts[category] = allMethods[category]?.length || 0;
+    });
+    return {
+      totalEndpoints: categories.length,
+      totalMethods,
+      categories,
+      methodCounts
+    };
+  }
+  /**
+   * Check if a specific method exists on an endpoint
+   * @param fmp - The FMP client instance
+   * @param endpoint - The endpoint category name
+   * @param method - The method name
+   * @returns True if the method exists
+   */
+  static hasMethod(fmp, endpoint, method) {
+    const methods = this.getEndpointMethods(fmp, endpoint);
+    return methods.includes(method);
+  }
+  /**
+   * Get method signature information (basic introspection)
+   * @param fmp - The FMP client instance
+   * @param endpoint - The endpoint category name
+   * @param method - The method name
+   * @returns Method information or null if not found
+   */
+  static getMethodInfo(fmp, endpoint, method) {
+    const endpointObj = fmp[endpoint];
+    if (!endpointObj || typeof endpointObj !== "object") {
+      return null;
+    }
+    const methodFn = endpointObj[method];
+    if (typeof methodFn !== "function") {
+      return null;
+    }
+    return {
+      name: method,
+      type: "function",
+      async: methodFn.constructor.name === "AsyncFunction"
+    };
+  }
+};
+
+// src/utils/utils.ts
+var FMPUtils = class {
+  /**
+   * Format currency values
+   * @param value - The numeric value to format
+   * @param currency - The currency code (default: USD)
+   * @param locale - The locale for formatting (default: en-US)
+   * @returns Formatted currency string
+   */
+  static formatCurrency(value, currency = "USD", locale = "en-US") {
+    if (typeof value !== "number" || isNaN(value)) {
+      return "N/A";
+    }
+    try {
+      return new Intl.NumberFormat(locale, {
+        style: "currency",
+        currency,
+        minimumFractionDigits: 2,
+        maximumFractionDigits: 2
+      }).format(value);
+    } catch (error) {
+      return `${currency} ${value.toFixed(2)}`;
+    }
+  }
+  /**
+   * Format percentages
+   * @param value - The percentage value (as decimal, e.g., 0.15 for 15%)
+   * @param decimals - Number of decimal places (default: 2)
+   * @returns Formatted percentage string
+   */
+  static formatPercentage(value, decimals = 2) {
+    if (typeof value !== "number" || isNaN(value)) {
+      return "N/A";
+    }
+    return `${value.toFixed(decimals)}%`;
+  }
+  /**
+   * Format large numbers with abbreviations (K, M, B, T)
+   * @param value - The numeric value to format
+   * @param decimals - Number of decimal places (default: 1)
+   * @returns Formatted number string
+   */
+  static formatLargeNumber(value, decimals = 1) {
+    if (typeof value !== "number" || isNaN(value)) {
+      return "N/A";
+    }
+    const absValue = Math.abs(value);
+    const sign = value < 0 ? "-" : "";
+    if (absValue >= 1e12) {
+      return `${sign}${(absValue / 1e12).toFixed(decimals)}T`;
+    } else if (absValue >= 1e9) {
+      return `${sign}${(absValue / 1e9).toFixed(decimals)}B`;
+    } else if (absValue >= 1e6) {
+      return `${sign}${(absValue / 1e6).toFixed(decimals)}M`;
+    } else if (absValue >= 1e3) {
+      return `${sign}${(absValue / 1e3).toFixed(decimals)}K`;
+    } else {
+      return `${sign}${absValue.toFixed(decimals)}`;
+    }
+  }
+  /**
+   * Convert date string to Date object
+   * @param dateString - The date string in YYYY-MM-DD format
+   * @returns Date object or null if invalid
+   */
+  static parseDate(dateString) {
+    if (!dateString || typeof dateString !== "string") {
+      return null;
+    }
+    const [year, month, day] = dateString.split("-").map(Number);
+    if (isNaN(year) || isNaN(month) || isNaN(day)) {
+      return null;
+    }
+    if (month < 1 || month > 12) {
+      return null;
+    }
+    const date = new Date(Date.UTC(year, month - 1, day));
+    if (isNaN(date.getTime())) {
+      return null;
+    }
+    const parsedYear = date.getUTCFullYear();
+    const parsedMonth = date.getUTCMonth() + 1;
+    const parsedDay = date.getUTCDate();
+    if (parsedYear !== year || parsedMonth !== month || parsedDay !== day) {
+      return null;
+    }
+    return date;
+  }
+  /**
+   * Format date to readable string
+   * @param date - Date object or date string
+   * @param format - Format style ('short', 'long', 'iso')
+   * @returns Formatted date string
+   */
+  static formatDate(date, format = "short") {
+    const dateObj = typeof date === "string" ? this.parseDate(date) : date;
+    if (!dateObj) {
+      return "Invalid Date";
+    }
+    switch (format) {
+      case "long":
+        return dateObj.toLocaleDateString("en-US", {
+          weekday: "long",
+          year: "numeric",
+          month: "long",
+          day: "numeric"
+        });
+      case "iso":
+        return dateObj.toISOString().split("T")[0];
+      case "short":
+      default:
+        return dateObj.toLocaleDateString("en-US", {
+          year: "numeric",
+          month: "short",
+          day: "numeric"
+        });
+    }
+  }
+  /**
+   * Calculate working days between two dates (excluding weekends)
+   * @param from - Start date
+   * @param to - End date
+   * @returns Number of working days
+   */
+  static getWorkingDays(from, to) {
+    const startDate = typeof from === "string" ? this.parseDate(from) : from;
+    const endDate = typeof to === "string" ? this.parseDate(to) : to;
+    if (!startDate || !endDate) {
+      return 0;
+    }
+    let workingDays = 0;
+    const currentDate = new Date(startDate);
+    const endDateNormalized = new Date(
+      Date.UTC(endDate.getUTCFullYear(), endDate.getUTCMonth(), endDate.getUTCDate())
+    );
+    while (currentDate <= endDateNormalized) {
+      const dayOfWeek = currentDate.getUTCDay();
+      if (dayOfWeek !== 0 && dayOfWeek !== 6) {
+        workingDays++;
+      }
+      currentDate.setUTCDate(currentDate.getUTCDate() + 1);
+    }
+    return workingDays;
+  }
+  /**
+   * Calculate percentage change between two values
+   * @param oldValue - The original value
+   * @param newValue - The new value
+   * @param decimals - Number of decimal places (default: 2)
+   * @returns Percentage change as a number
+   */
+  static calculatePercentageChange(oldValue, newValue, decimals = 2) {
+    if (typeof oldValue !== "number" || typeof newValue !== "number" || isNaN(oldValue) || isNaN(newValue) || oldValue === 0) {
+      return 0;
+    }
+    const change = (newValue - oldValue) / oldValue * 100;
+    return Number(change.toFixed(decimals));
+  }
+  /**
+   * Batch API calls with rate limiting
+   * @param calls - Array of async functions to execute
+   * @param delayMs - Delay between calls in milliseconds (default: 100)
+   * @param maxConcurrent - Maximum concurrent calls (default: 1)
+   * @returns Array of results
+   */
+  static async batchCalls(calls, delayMs = 100, maxConcurrent = 1) {
+    const results = [];
+    if (maxConcurrent === 1) {
+      for (const call of calls) {
+        results.push(await call());
+        if (delayMs > 0) {
+          await new Promise((resolve) => setTimeout(resolve, delayMs));
+        }
+      }
+    } else {
+      const chunks = this.chunkArray(calls, maxConcurrent);
+      for (const chunk of chunks) {
+        const chunkResults = await Promise.all(chunk.map((call) => call()));
+        results.push(...chunkResults);
+        if (delayMs > 0) {
+          await new Promise((resolve) => setTimeout(resolve, delayMs));
+        }
+      }
+    }
+    return results;
+  }
+  /**
+   * Split array into chunks
+   * @param array - The array to split
+   * @param chunkSize - Size of each chunk
+   * @returns Array of chunks
+   */
+  static chunkArray(array, chunkSize) {
+    const chunks = [];
+    for (let i = 0; i < array.length; i += chunkSize) {
+      chunks.push(array.slice(i, i + chunkSize));
+    }
+    return chunks;
+  }
+  /**
+   * Retry a function with exponential backoff
+   * @param fn - The function to retry
+   * @param maxRetries - Maximum number of retries (default: 3)
+   * @param baseDelay - Base delay in milliseconds (default: 1000)
+   * @returns Function result
+   */
+  static async retryWithBackoff(fn, maxRetries = 3, baseDelay = 1e3) {
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        return await fn();
+      } catch (error) {
+        lastError = error;
+        if (attempt === maxRetries) {
+          throw lastError;
+        }
+        const delay = baseDelay * Math.pow(2, attempt);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+    }
+    throw lastError;
+  }
+  /**
+   * Debounce a function
+   * @param func - The function to debounce
+   * @param wait - Wait time in milliseconds
+   * @returns Debounced function
+   */
+  static debounce(func, wait) {
+    let timeout;
+    return (...args) => {
+      clearTimeout(timeout);
+      timeout = setTimeout(() => func(...args), wait);
+    };
+  }
+  /**
+   * Throttle a function
+   * @param func - The function to throttle
+   * @param limit - Time limit in milliseconds
+   * @returns Throttled function
+   */
+  static throttle(func, limit) {
+    let inThrottle;
+    return (...args) => {
+      if (!inThrottle) {
+        func(...args);
+        inThrottle = true;
+        setTimeout(() => inThrottle = false, limit);
+      }
+    };
+  }
+};
+
+// src/utils/debug.ts
+var _FMPDebug = class _FMPDebug {
+  /**
+   * Log API calls for debugging (only in development)
+   * @param endpoint - The endpoint being called
+   * @param params - The parameters passed to the endpoint
+   * @param response - The response received
+   * @param duration - The duration of the call in milliseconds
+   */
+  static logApiCall(endpoint, params, response, duration) {
+    if (!this.isDevelopment && !this.isDebugEnabled) {
+      return;
+    }
+    const logData = {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      endpoint,
+      params,
+      success: response?.success,
+      status: response?.status,
+      duration: duration ? `${duration}ms` : void 0
+    };
+    console.log("\u{1F50D} FMP API Call:", logData);
+  }
+  /**
+   * Log API errors for debugging
+   * @param endpoint - The endpoint that failed
+   * @param params - The parameters that were passed
+   * @param error - The error that occurred
+   */
+  static logApiError(endpoint, params, error) {
+    if (!this.isDevelopment && !this.isDebugEnabled) {
+      return;
+    }
+    console.error("\u274C FMP API Error:", {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      endpoint,
+      params,
+      error: error?.message || error,
+      stack: error?.stack
+    });
+  }
+  /**
+   * Get comprehensive API usage statistics
+   * @param fmp - The FMP client instance
+   * @returns Detailed API statistics
+   */
+  static getApiStats(fmp) {
+    const summary = FMPHelpers.getApiSummary(fmp);
+    const estimatedApiCalls = Object.values(summary.methodCounts).reduce(
+      (total, count) => total + count * 2,
+      // Assume 2 calls per method on average
+      0
+    );
+    return {
+      ...summary,
+      estimatedApiCalls
+    };
+  }
+  /**
+   * Validate API key format and provide feedback
+   * @param apiKey - The API key to validate
+   * @returns Validation result with details
+   */
+  static validateApiKey(apiKey) {
+    const length = apiKey?.length || 0;
+    const format = apiKey?.match(/^[a-zA-Z0-9]+$/) ? "alphanumeric" : "invalid";
+    const isValid = length >= 32 && format === "alphanumeric";
+    const suggestions = [];
+    if (length < 32) {
+      suggestions.push("API key should be at least 32 characters long");
+    }
+    if (format !== "alphanumeric") {
+      suggestions.push("API key should contain only letters and numbers");
+    }
+    if (!apiKey) {
+      suggestions.push("API key is required");
+    }
+    return {
+      isValid,
+      length,
+      format,
+      suggestions
+    };
+  }
+  /**
+   * Check API key environment variable
+   * @returns Environment check result
+   */
+  static checkApiKeyEnvironment() {
+    const envVarName = "FMP_API_KEY";
+    const apiKey = process.env[envVarName];
+    const hasEnvVar = !!apiKey;
+    const validation = this.validateApiKey(apiKey || "");
+    const suggestions = [];
+    if (!hasEnvVar) {
+      suggestions.push(`Set ${envVarName} environment variable`);
+      suggestions.push("Add to your .env file: FMP_API_KEY=your_api_key_here");
+    } else if (!validation.isValid) {
+      suggestions.push(...validation.suggestions);
+    }
+    return {
+      hasEnvVar,
+      envVarName,
+      isValid: validation.isValid,
+      suggestions
+    };
+  }
+  /**
+   * Get performance metrics for API calls
+   * @param fmp - The FMP client instance
+   * @returns Performance information
+   */
+  static getPerformanceInfo() {
+    return {
+      nodeVersion: process.version,
+      platform: process.platform,
+      memoryUsage: process.memoryUsage(),
+      uptime: process.uptime()
+    };
+  }
+  /**
+   * Create a debug configuration object
+   * @param fmp - The FMP client instance
+   * @returns Debug configuration
+   */
+  static createDebugConfig(fmp) {
+    return {
+      apiStats: this.getApiStats(fmp),
+      envCheck: this.checkApiKeyEnvironment(),
+      performance: this.getPerformanceInfo(),
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  /**
+   * Print debug information to console
+   * @param fmp - The FMP client instance
+   */
+  static printDebugInfo(fmp) {
+    if (!this.isDevelopment && !this.isDebugEnabled) {
+      return;
+    }
+    const config = this.createDebugConfig(fmp);
+    console.log("\u{1F527} FMP Debug Information:");
+    console.log("\u{1F4CA} API Stats:", config.apiStats);
+    console.log("\u{1F511} Environment Check:", config.envCheck);
+    console.log("\u26A1 Performance:", config.performance);
+    console.log("\u{1F552} Timestamp:", config.timestamp);
+  }
+  /**
+   * Enable debug mode programmatically
+   */
+  static enableDebugMode() {
+    process.env.FMP_DEBUG = "true";
+    this.isDebugEnabled = true;
+    console.log("\u{1F527} FMP Debug mode enabled");
+  }
+  /**
+   * Disable debug mode programmatically
+   */
+  static disableDebugMode() {
+    process.env.FMP_DEBUG = "false";
+    this.isDebugEnabled = false;
+    console.log("\u{1F527} FMP Debug mode disabled");
+  }
+  /**
+   * Check if debug mode is enabled
+   * @returns True if debug mode is enabled
+   */
+  static isDebugMode() {
+    return this.isDevelopment || this.isDebugEnabled;
+  }
+  /**
+   * Create a debug wrapper for API calls
+   * @param fmp - The FMP client instance
+   * @returns FMP client with debug logging
+   */
+  static createDebugWrapper(fmp) {
+    if (!this.isDebugMode()) {
+      return fmp;
+    }
+    return new Proxy(fmp, {
+      get(target, prop) {
+        const value = target[prop];
+        if (typeof value === "object" && value !== null) {
+          return new Proxy(value, {
+            get(endpointTarget, methodName) {
+              const method = endpointTarget[methodName];
+              if (typeof method === "function") {
+                return async (...args) => {
+                  const startTime = Date.now();
+                  const endpoint = `${String(prop)}.${String(methodName)}`;
+                  let params;
+                  if (methodName === "getQuote" && args.length === 1 && typeof args[0] === "string") {
+                    params = { symbol: args[0] };
+                  } else if (args.length === 1 && typeof args[0] === "object" && args[0] !== null) {
+                    params = args[0];
+                  } else {
+                    params = args;
+                  }
+                  try {
+                    _FMPDebug.logApiCall(endpoint, params, null);
+                    const result = await method.apply(
+                      endpointTarget,
+                      args
+                    );
+                    const duration = Date.now() - startTime;
+                    _FMPDebug.logApiCall(endpoint, params, result, duration);
+                    return result;
+                  } catch (error) {
+                    _FMPDebug.logApiError(endpoint, params, error);
+                    throw error;
+                  }
+                };
+              }
+              return method;
+            }
+          });
+        }
+        return value;
+      }
+    });
+  }
+};
+_FMPDebug.isDevelopment = process.env.NODE_ENV === "development";
+_FMPDebug.isDebugEnabled = process.env.FMP_DEBUG === "true";
+var FMPDebug = _FMPDebug;
+
+export { COUNTRIES, CalendarEndpoints, CompanyEndpoints, DEFAULT_LIMIT, DEFAULT_TIMEOUT, ERROR_MESSAGES, ETFEndpoints, EXCHANGES, EconomicEndpoints, Exchange, FMP, FMPClient, FMPDebug, FMPHelpers, FMPUtils, FMPValidation, FinancialEndpoints, HTTP_STATUS, InsiderEndpoints, InstitutionalEndpoints, ListEndpoints, MAX_LIMIT, MarketEndpoints, MutualFundEndpoints, PERIODS, Period, QuoteEndpoints, SECEndpoints, SECTORS, SenateHouseEndpoints, StockEndpoints, TransactionType, formatCurrency, formatDate, formatLargeNumber, formatNumber, formatPercentage, formatReadableDate, formatTimestamp, formatVolume };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map