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

package/README.md

@@ -7,44 +7,39 @@ This package provides pre-built AI tools that can be used with various AI framew
 ## Installation
 
 ```bash
-npm install fmp-ai-tools
-# or
-pnpm add fmp-ai-tools
-# or
-yarn add fmp-ai-tools
+pnpm add fmp-ai-tools     # or: npm install fmp-ai-tools / yarn add fmp-ai-tools
 ```
 
-### Peer Dependencies
+`fmp-ai-tools` has two entry points. `ai` and `@openai/agents` are **optional peer dependencies**, so install only the SDK for the entry point you use, plus `zod`.
 
-This package requires the following peer dependencies to be installed in your project:
+### Vercel AI SDK — `fmp-ai-tools/vercel-ai`
 
 ```bash
-# For Vercel AI SDK
-npm install ai zod
-# or
 pnpm add ai zod
-# or
-yarn add ai zod
 ```
 
-**Required versions:**
+- `ai`: `>=6.0.0`
+- `zod`: `^4.0.0`
 
-- `ai`: ^5.0.0
-- `zod`: ^3.25.76
+### OpenAI Agents — `fmp-ai-tools/openai`
 
-**⚠️ Common Issue**: If you encounter the error `Invalid schema for function 'getStockQuote': schema must be a JSON Schema of 'type: "object"', got 'type: "None"'`, it means you have a version mismatch between `ai` and `zod`. Make sure you're using compatible versions as listed above.
-
-## Version Compatibility
+```bash
+pnpm add @openai/agents zod
+```
 
-### OpenAI Agents Compatibility
+- `@openai/agents`: `>=0.11.0`
+- `zod`: `^4.0.0`
 
-**⚠️ Important**: This package requires `@openai/agents` version `^0.1.0` or higher due to breaking changes in the API. Older versions are not supported and will fail when the tools are imported.
+Both entry points are imported with a normal static `import` — no `serverExternalPackages`, `createRequire`, or other bundler workarounds are needed (Next.js App Router and Turbopack included).
 
 ## Quick Start
 
 ### Vercel AI SDK (Recommended)
 
+`convertToModelMessages` is **async in `ai` v6** — be sure to `await` it.
+
 ```typescript
+// app/api/chat/route.ts
 import { openai } from '@ai-sdk/openai';
 import { streamText, convertToModelMessages, stepCountIs } from 'ai';
 import { fmpTools } from 'fmp-ai-tools/vercel-ai';
@@ -54,9 +49,12 @@ export async function POST(req: Request) {
 
   const result = streamText({
     model: openai('gpt-4o-mini'),
-    messages: convertToModelMessages(messages),
+    messages: await convertToModelMessages(messages),
     tools: fmpTools,
     stopWhen: stepCountIs(5),
+    // FMP tools have optional params; relax strict JSON schema so the model
+    // can omit them (@ai-sdk/openai v3 defaults strictJsonSchema: true).
+    providerOptions: { openai: { strictJsonSchema: false } },
   });
 
   return result.toUIMessageStreamResponse();
@@ -66,19 +64,24 @@ export async function POST(req: Request) {
 ### OpenAI Agents
 
 ```typescript
+// app/api/chat/route.ts
 import { Agent, run } from '@openai/agents';
 import { fmpTools } from 'fmp-ai-tools/openai';
 
 const agent = new Agent({
   name: 'Financial Analyst',
+  model: 'gpt-4o-mini',
   instructions: 'You are a financial analyst with access to real-time market data.',
   tools: fmpTools,
 });
 
-const result = await run(
-  agent,
-  'Get the current stock quote for Apple (AAPL) and show me their latest balance sheet',
-);
+export async function POST(req: Request) {
+  const { message } = await req.json();
+
+  const result = await run(agent, message);
+
+  return Response.json({ output: result.finalOutput });
+}
 ```
 
 ## Configuration
@@ -222,7 +225,7 @@ const selectedTools = {
 // Use with Vercel AI SDK
 const result = streamText({
   model: openai('gpt-4o-mini'),
-  messages: convertToModelMessages(messages),
+  messages: await convertToModelMessages(messages),
   tools: selectedTools,
 });
 ```
@@ -299,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:
+
+```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                                                |
 
-- The API key is invalid or missing
-- The requested data is not available
-- Rate limits are exceeded
-- Invalid parameters are provided
+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

@@ -1,83 +1,10 @@
 'use strict';
 
-var fs = require('fs');
-var path = require('path');
 var zod = require('zod');
 var agents = require('@openai/agents');
 var fmpNodeApi = require('fmp-node-api');
 
-function _interopNamespace(e) {
-  if (e && e.__esModule) return e;
-  var n = Object.create(null);
-  if (e) {
-    Object.keys(e).forEach(function (k) {
-      if (k !== 'default') {
-        var d = Object.getOwnPropertyDescriptor(e, k);
-        Object.defineProperty(n, k, d.get ? d : {
-          enumerable: true,
-          get: function () { return e[k]; }
-        });
-      }
-    });
-  }
-  n.default = e;
-  return Object.freeze(n);
-}
-
-var fs__namespace = /*#__PURE__*/_interopNamespace(fs);
-var path__namespace = /*#__PURE__*/_interopNamespace(path);
-
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
-var REQUIRED_VERSION = "0.11.0";
-function getInstalledPackageVersion(packageName) {
-  try {
-    const packagePath = path__namespace.dirname(__require.resolve(packageName));
-    const packageJsonPath = path__namespace.join(packagePath, "..", "package.json");
-    if (fs__namespace.existsSync(packageJsonPath)) {
-      const packageJson = JSON.parse(fs__namespace.readFileSync(packageJsonPath, "utf8"));
-      return packageJson.version;
-    }
-  } catch (_error) {
-    return null;
-  }
-  return null;
-}
-function compareVersions(v1, v2) {
-  const parseVersion = (version) => {
-    return version.split(".").map((num) => parseInt(num, 10) || 0);
-  };
-  const v1Parts = parseVersion(v1);
-  const v2Parts = parseVersion(v2);
-  const maxLength = Math.max(v1Parts.length, v2Parts.length);
-  for (let i = 0; i < maxLength; i++) {
-    const v1Part = v1Parts[i] || 0;
-    const v2Part = v2Parts[i] || 0;
-    if (v1Part < v2Part) return -1;
-    if (v1Part > v2Part) return 1;
-  }
-  return 0;
-}
-function isVersionLessThan(installedVersion, requiredVersion) {
-  return compareVersions(installedVersion, requiredVersion) < 0;
-}
-function checkOpenAIAgentsVersion() {
-  const installedVersion = getInstalledPackageVersion("@openai/agents");
-  if (!installedVersion) {
-    throw new Error(
-      `@openai/agents package not found. This package requires @openai/agents to be installed. Please install with: npm install @openai/agents`
-    );
-  }
-  if (isVersionLessThan(installedVersion, REQUIRED_VERSION)) {
-    console.warn(
-      `Incompatible @openai/agents version detected. Installed version: ${installedVersion}, Required: ${REQUIRED_VERSION} or higher.`
-    );
-  }
-}
+// src/providers/openai/company.ts
 
 // src/utils/logger.ts
 function isApiLoggingEnabled() {
@@ -250,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;
@@ -258,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);
+      }
     }
   });
 }
@@ -277,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({
@@ -289,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({
@@ -301,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({
@@ -318,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({
@@ -331,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({
@@ -378,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({
@@ -392,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({
@@ -413,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({
@@ -423,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({
@@ -441,7 +402,7 @@ var getBalanceSheet = createOpenAITool({
       period,
       limit: Number(limit)
     });
-    return JSON.stringify(balanceSheet.data, null, 2);
+    return toToolResponse(balanceSheet);
   }
 });
 var getIncomeStatement = createOpenAITool({
@@ -459,7 +420,7 @@ var getIncomeStatement = createOpenAITool({
       period,
       limit: Number(limit)
     });
-    return JSON.stringify(incomeStatement.data, null, 2);
+    return toToolResponse(incomeStatement);
   }
 });
 var getCashFlowStatement = createOpenAITool({
@@ -477,7 +438,7 @@ var getCashFlowStatement = createOpenAITool({
       period,
       limit: Number(limit)
     });
-    return JSON.stringify(cashFlowStatement.data, null, 2);
+    return toToolResponse(cashFlowStatement);
   }
 });
 var getKeyMetrics = createOpenAITool({
@@ -491,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({
@@ -509,7 +470,7 @@ var getFinancialRatios = createOpenAITool({
       period,
       limit: Number(limit)
     });
-    return JSON.stringify(financialRatios.data, null, 2);
+    return toToolResponse(financialRatios);
   }
 });
 var getEnterpriseValue = createOpenAITool({
@@ -527,7 +488,7 @@ var getEnterpriseValue = createOpenAITool({
       period,
       limit: Number(limit)
     });
-    return JSON.stringify(enterpriseValue.data, null, 2);
+    return toToolResponse(enterpriseValue);
   }
 });
 var getCashflowGrowth = createOpenAITool({
@@ -545,7 +506,7 @@ var getCashflowGrowth = createOpenAITool({
       period,
       limit: Number(limit)
     });
-    return JSON.stringify(cashflowGrowth.data, null, 2);
+    return toToolResponse(cashflowGrowth);
   }
 });
 var getIncomeGrowth = createOpenAITool({
@@ -563,7 +524,7 @@ var getIncomeGrowth = createOpenAITool({
       period,
       limit: Number(limit)
     });
-    return JSON.stringify(incomeGrowth.data, null, 2);
+    return toToolResponse(incomeGrowth);
   }
 });
 var getBalanceSheetGrowth = createOpenAITool({
@@ -581,7 +542,7 @@ var getBalanceSheetGrowth = createOpenAITool({
       period,
       limit: Number(limit)
     });
-    return JSON.stringify(balanceSheetGrowth.data, null, 2);
+    return toToolResponse(balanceSheetGrowth);
   }
 });
 var getFinancialGrowth = createOpenAITool({
@@ -599,7 +560,7 @@ var getFinancialGrowth = createOpenAITool({
       period,
       limit: Number(limit)
     });
-    return JSON.stringify(financialGrowth.data, null, 2);
+    return toToolResponse(financialGrowth);
   }
 });
 var getEarningsHistorical = createOpenAITool({
@@ -615,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({
@@ -629,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({
@@ -642,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({});
@@ -653,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({
@@ -663,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({
@@ -673,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({
@@ -683,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({
@@ -693,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({
@@ -706,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({
@@ -725,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({
@@ -735,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({
@@ -745,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({
@@ -755,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({
@@ -765,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({
@@ -775,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({
@@ -788,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({
@@ -798,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({
@@ -808,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);
   }
 });
 
@@ -892,7 +853,6 @@ var fmpTools = [
   getStockSplits,
   getDividendHistory
 ];
-checkOpenAIAgentsVersion();
 
 exports.calendarTools = calendarTools;
 exports.companyTools = companyTools;