fmp-ai-tools 0.2.0-beta.2 → 0.2.0-beta.4

package/README.md

@@ -302,12 +302,25 @@ Each tool accepts specific parameters. Here are some common ones:
 
 ## Error Handling
 
-The tools handle API errors gracefully and will return informative error messages if:
+When a request fails, a tool returns a structured JSON error (instead of `null`) so the model can explain *why* to the user:
 
-- The API key is invalid or missing
-- The requested data is not available
-- Rate limits are exceeded
-- Invalid parameters are provided
+```json
+{ "error": true, "type": "plan-restricted", "message": "This endpoint is not available on your current FMP plan. (403: ...)", "status": 403 }
+```
+
+The `type` field classifies the failure so your agent can react appropriately:
+
+| `type`            | Meaning                                                      |
+| ----------------- | ------------------------------------------------------------ |
+| `plan-restricted` | Endpoint isn't included in your FMP subscription (402/403)   |
+| `rate-limit`      | FMP quota / rate limit reached (429)                         |
+| `auth`            | Invalid or missing `FMP_API_KEY` (401)                       |
+| `not-found`       | Resource does not exist (404)                                |
+| `bad-request`     | Invalid parameters (400)                                     |
+| `network`         | No response from FMP (timeout / offline)                     |
+| `unknown`         | Anything else                                                |
+
+This is especially useful on lower FMP tiers: an agent calling an endpoint your plan doesn't cover now gets a clear `plan-restricted` message it can relay, rather than empty data. (Direct `fmp-node-api` callers get the same classification via `response.errorType`.)
 
 ## Testing Tools
 

package/dist/providers/openai/index.js

@@ -177,6 +177,36 @@ async function logApiExecutionWithTiming(toolName, input, executeFn) {
   }
 }
 
+// src/utils/format-response.ts
+function toToolResponse(res) {
+  if (res.success === false) {
+    return JSON.stringify({
+      error: true,
+      type: res.errorType ?? "unknown",
+      message: res.error ?? "The request failed.",
+      status: res.status
+    });
+  }
+  if (isEmpty(res.data)) {
+    return JSON.stringify({ data: [], note: "No data was returned for this request." });
+  }
+  return JSON.stringify(res.data, null, 2);
+}
+function toToolError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  let type = "unknown";
+  if (/api[\s_-]?key/i.test(message)) {
+    type = "auth";
+  }
+  return JSON.stringify({ error: true, type, message, status: 0 });
+}
+function isEmpty(data) {
+  if (data == null) return true;
+  if (Array.isArray(data)) return data.length === 0;
+  if (typeof data === "object") return Object.keys(data).length === 0;
+  return false;
+}
+
 // src/utils/openai-tool-wrapper.ts
 function createOpenAITool(config) {
   const { name, description, inputSchema, execute } = config;
@@ -185,8 +215,12 @@ function createOpenAITool(config) {
     description,
     parameters: inputSchema,
     execute: async (input) => {
-      const args = inputSchema.parse(input);
-      return await logApiExecutionWithTiming(name, args, () => execute(args));
+      try {
+        const args = inputSchema.parse(input);
+        return await logApiExecutionWithTiming(name, args, () => execute(args));
+      } catch (error) {
+        return toToolError(error);
+      }
     }
   });
 }
@@ -204,7 +238,7 @@ var getCompanyProfile = createOpenAITool({
   execute: async ({ symbol }) => {
     const fmp = getFMPClient();
     const companyProfile = await fmp.company.getCompanyProfile(symbol);
-    return JSON.stringify(companyProfile.data, null, 2);
+    return toToolResponse(companyProfile);
   }
 });
 var getCompanySharesFloat = createOpenAITool({
@@ -216,7 +250,7 @@ var getCompanySharesFloat = createOpenAITool({
   execute: async ({ symbol }) => {
     const fmp = getFMPClient();
     const companySharesFloat = await fmp.company.getSharesFloat(symbol);
-    return JSON.stringify(companySharesFloat.data, null, 2);
+    return toToolResponse(companySharesFloat);
   }
 });
 var getCompanyExecutiveCompensation = createOpenAITool({
@@ -228,7 +262,7 @@ var getCompanyExecutiveCompensation = createOpenAITool({
   execute: async ({ symbol }) => {
     const fmp = getFMPClient();
     const companyExecutiveCompensation = await fmp.company.getExecutiveCompensation(symbol);
-    return JSON.stringify(companyExecutiveCompensation.data, null, 2);
+    return toToolResponse(companyExecutiveCompensation);
   }
 });
 var calendarInputSchema = zod.z.object({
@@ -245,7 +279,7 @@ var getEarningsCalendar = createOpenAITool({
       from: from ?? void 0,
       to: to ?? void 0
     });
-    return JSON.stringify(earningsCalendar.data, null, 2);
+    return toToolResponse(earningsCalendar);
   }
 });
 var getEconomicCalendar = createOpenAITool({
@@ -258,7 +292,7 @@ var getEconomicCalendar = createOpenAITool({
       from: from ?? void 0,
       to: to ?? void 0
     });
-    return JSON.stringify(economicCalendar.data, null, 2);
+    return toToolResponse(economicCalendar);
   }
 });
 var treasuryRatesInputSchema = zod.z.object({
@@ -305,7 +339,7 @@ var getTreasuryRates = createOpenAITool({
       from: from ?? void 0,
       to: to ?? void 0
     });
-    return JSON.stringify(treasuryRates.data, null, 2);
+    return toToolResponse(treasuryRates);
   }
 });
 var getEconomicIndicators = createOpenAITool({
@@ -319,7 +353,7 @@ var getEconomicIndicators = createOpenAITool({
       from: from ?? void 0,
       to: to ?? void 0
     });
-    return JSON.stringify(economicIndicators.data, null, 2);
+    return toToolResponse(economicIndicators);
   }
 });
 var etfHoldingsInputSchema = zod.z.object({
@@ -340,7 +374,7 @@ var getETFHoldings = createOpenAITool({
       params.date = date;
     }
     const etfHoldings = await fmp.etf.getHoldings(params);
-    return JSON.stringify(etfHoldings.data, null, 2);
+    return toToolResponse(etfHoldings);
   }
 });
 var getETFProfile = createOpenAITool({
@@ -350,7 +384,7 @@ var getETFProfile = createOpenAITool({
   execute: async ({ symbol }) => {
     const fmp = getFMPClient();
     const etfProfile = await fmp.etf.getProfile(symbol);
-    return JSON.stringify(etfProfile.data, null, 2);
+    return toToolResponse(etfProfile);
   }
 });
 var getBalanceSheet = createOpenAITool({
@@ -368,7 +402,7 @@ var getBalanceSheet = createOpenAITool({
       period,
       limit: Number(limit)
     });
-    return JSON.stringify(balanceSheet.data, null, 2);
+    return toToolResponse(balanceSheet);
   }
 });
 var getIncomeStatement = createOpenAITool({
@@ -386,7 +420,7 @@ var getIncomeStatement = createOpenAITool({
       period,
       limit: Number(limit)
     });
-    return JSON.stringify(incomeStatement.data, null, 2);
+    return toToolResponse(incomeStatement);
   }
 });
 var getCashFlowStatement = createOpenAITool({
@@ -404,7 +438,7 @@ var getCashFlowStatement = createOpenAITool({
       period,
       limit: Number(limit)
     });
-    return JSON.stringify(cashFlowStatement.data, null, 2);
+    return toToolResponse(cashFlowStatement);
   }
 });
 var getKeyMetrics = createOpenAITool({
@@ -418,7 +452,7 @@ var getKeyMetrics = createOpenAITool({
   execute: async ({ symbol, period, limit }) => {
     const fmp = getFMPClient();
     const keyMetrics = await fmp.financial.getKeyMetrics({ symbol, period, limit: Number(limit) });
-    return JSON.stringify(keyMetrics.data, null, 2);
+    return toToolResponse(keyMetrics);
   }
 });
 var getFinancialRatios = createOpenAITool({
@@ -436,7 +470,7 @@ var getFinancialRatios = createOpenAITool({
       period,
       limit: Number(limit)
     });
-    return JSON.stringify(financialRatios.data, null, 2);
+    return toToolResponse(financialRatios);
   }
 });
 var getEnterpriseValue = createOpenAITool({
@@ -454,7 +488,7 @@ var getEnterpriseValue = createOpenAITool({
       period,
       limit: Number(limit)
     });
-    return JSON.stringify(enterpriseValue.data, null, 2);
+    return toToolResponse(enterpriseValue);
   }
 });
 var getCashflowGrowth = createOpenAITool({
@@ -472,7 +506,7 @@ var getCashflowGrowth = createOpenAITool({
       period,
       limit: Number(limit)
     });
-    return JSON.stringify(cashflowGrowth.data, null, 2);
+    return toToolResponse(cashflowGrowth);
   }
 });
 var getIncomeGrowth = createOpenAITool({
@@ -490,7 +524,7 @@ var getIncomeGrowth = createOpenAITool({
       period,
       limit: Number(limit)
     });
-    return JSON.stringify(incomeGrowth.data, null, 2);
+    return toToolResponse(incomeGrowth);
   }
 });
 var getBalanceSheetGrowth = createOpenAITool({
@@ -508,7 +542,7 @@ var getBalanceSheetGrowth = createOpenAITool({
       period,
       limit: Number(limit)
     });
-    return JSON.stringify(balanceSheetGrowth.data, null, 2);
+    return toToolResponse(balanceSheetGrowth);
   }
 });
 var getFinancialGrowth = createOpenAITool({
@@ -526,7 +560,7 @@ var getFinancialGrowth = createOpenAITool({
       period,
       limit: Number(limit)
     });
-    return JSON.stringify(financialGrowth.data, null, 2);
+    return toToolResponse(financialGrowth);
   }
 });
 var getEarningsHistorical = createOpenAITool({
@@ -542,7 +576,7 @@ var getEarningsHistorical = createOpenAITool({
       symbol,
       limit: Number(limit)
     });
-    return JSON.stringify(earningsHistorical.data, null, 2);
+    return toToolResponse(earningsHistorical);
   }
 });
 var insiderTradingInputSchema = zod.z.object({
@@ -556,7 +590,7 @@ var getInsiderTrading = createOpenAITool({
   execute: async ({ symbol, page }) => {
     const fmp = getFMPClient();
     const insiderTrading = await fmp.insider.getInsiderTradesBySymbol(symbol, page);
-    return JSON.stringify(insiderTrading.data, null, 2);
+    return toToolResponse(insiderTrading);
   }
 });
 var institutionalHoldersInputSchema = zod.z.object({
@@ -569,7 +603,7 @@ var getInstitutionalHolders = createOpenAITool({
   execute: async ({ symbol }) => {
     const fmp = getFMPClient();
     const institutionalHolders = await fmp.institutional.getInstitutionalHolders({ symbol });
-    return JSON.stringify(institutionalHolders.data, null, 2);
+    return toToolResponse(institutionalHolders);
   }
 });
 var emptyInputSchema = zod.z.object({});
@@ -580,7 +614,7 @@ var getMarketPerformance = createOpenAITool({
   execute: async () => {
     const fmp = getFMPClient();
     const marketPerformance = await fmp.market.getMarketPerformance();
-    return JSON.stringify(marketPerformance.data, null, 2);
+    return toToolResponse(marketPerformance);
   }
 });
 var getSectorPerformance = createOpenAITool({
@@ -590,7 +624,7 @@ var getSectorPerformance = createOpenAITool({
   execute: async () => {
     const fmp = getFMPClient();
     const sectorPerformance = await fmp.market.getSectorPerformance();
-    return JSON.stringify(sectorPerformance.data, null, 2);
+    return toToolResponse(sectorPerformance);
   }
 });
 var getGainers = createOpenAITool({
@@ -600,7 +634,7 @@ var getGainers = createOpenAITool({
   execute: async () => {
     const fmp = getFMPClient();
     const gainers = await fmp.market.getGainers();
-    return JSON.stringify(gainers.data, null, 2);
+    return toToolResponse(gainers);
   }
 });
 var getLosers = createOpenAITool({
@@ -610,7 +644,7 @@ var getLosers = createOpenAITool({
   execute: async () => {
     const fmp = getFMPClient();
     const losers = await fmp.market.getLosers();
-    return JSON.stringify(losers.data, null, 2);
+    return toToolResponse(losers);
   }
 });
 var getMostActive = createOpenAITool({
@@ -620,7 +654,7 @@ var getMostActive = createOpenAITool({
   execute: async () => {
     const fmp = getFMPClient();
     const mostActive = await fmp.market.getMostActive();
-    return JSON.stringify(mostActive.data, null, 2);
+    return toToolResponse(mostActive);
   }
 });
 var stockQuoteInputSchema = zod.z.object({
@@ -633,7 +667,7 @@ var getStockQuote = createOpenAITool({
   execute: async ({ symbol }) => {
     const fmp = getFMPClient();
     const stockQuote = await fmp.quote.getQuote(symbol);
-    return JSON.stringify(stockQuote.data, null, 2);
+    return toToolResponse(stockQuote);
   }
 });
 var symbolInputSchema = zod.z.object({
@@ -652,7 +686,7 @@ var getSenateTrading = createOpenAITool({
   execute: async ({ symbol }) => {
     const fmp = getFMPClient();
     const senateTrading = await fmp.senateHouse.getSenateTrading({ symbol });
-    return JSON.stringify(senateTrading.data, null, 2);
+    return toToolResponse(senateTrading);
   }
 });
 var getHouseTrading = createOpenAITool({
@@ -662,7 +696,7 @@ var getHouseTrading = createOpenAITool({
   execute: async ({ symbol }) => {
     const fmp = getFMPClient();
     const houseTrading = await fmp.senateHouse.getHouseTrading({ symbol });
-    return JSON.stringify(houseTrading.data, null, 2);
+    return toToolResponse(houseTrading);
   }
 });
 var getSenateTradingByName = createOpenAITool({
@@ -672,7 +706,7 @@ var getSenateTradingByName = createOpenAITool({
   execute: async ({ name }) => {
     const fmp = getFMPClient();
     const senateTradingByName = await fmp.senateHouse.getSenateTradingByName({ name });
-    return JSON.stringify(senateTradingByName.data, null, 2);
+    return toToolResponse(senateTradingByName);
   }
 });
 var getHouseTradingByName = createOpenAITool({
@@ -682,7 +716,7 @@ var getHouseTradingByName = createOpenAITool({
   execute: async ({ name }) => {
     const fmp = getFMPClient();
     const houseTradingByName = await fmp.senateHouse.getHouseTradingByName({ name });
-    return JSON.stringify(houseTradingByName.data, null, 2);
+    return toToolResponse(houseTradingByName);
   }
 });
 var getSenateTradingRSSFeed = createOpenAITool({
@@ -692,7 +726,7 @@ var getSenateTradingRSSFeed = createOpenAITool({
   execute: async ({ page }) => {
     const fmp = getFMPClient();
     const senateTradingRSSFeed = await fmp.senateHouse.getSenateTradingRSSFeed({ page });
-    return JSON.stringify(senateTradingRSSFeed.data, null, 2);
+    return toToolResponse(senateTradingRSSFeed);
   }
 });
 var getHouseTradingRSSFeed = createOpenAITool({
@@ -702,7 +736,7 @@ var getHouseTradingRSSFeed = createOpenAITool({
   execute: async ({ page }) => {
     const fmp = getFMPClient();
     const houseTradingRSSFeed = await fmp.senateHouse.getHouseTradingRSSFeed({ page });
-    return JSON.stringify(houseTradingRSSFeed.data, null, 2);
+    return toToolResponse(houseTradingRSSFeed);
   }
 });
 var symbolInputSchema2 = zod.z.object({
@@ -715,7 +749,7 @@ var getMarketCap = createOpenAITool({
   execute: async ({ symbol }) => {
     const fmp = getFMPClient();
     const marketCap = await fmp.stock.getMarketCap(symbol);
-    return JSON.stringify(marketCap.data, null, 2);
+    return toToolResponse(marketCap);
   }
 });
 var getStockSplits = createOpenAITool({
@@ -725,7 +759,7 @@ var getStockSplits = createOpenAITool({
   execute: async ({ symbol }) => {
     const fmp = getFMPClient();
     const stockSplits = await fmp.stock.getStockSplits(symbol);
-    return JSON.stringify(stockSplits.data, null, 2);
+    return toToolResponse(stockSplits);
   }
 });
 var getDividendHistory = createOpenAITool({
@@ -735,7 +769,7 @@ var getDividendHistory = createOpenAITool({
   execute: async ({ symbol }) => {
     const fmp = getFMPClient();
     const dividendHistory = await fmp.stock.getDividendHistory(symbol);
-    return JSON.stringify(dividendHistory.data, null, 2);
+    return toToolResponse(dividendHistory);
   }
 });