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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (14) hide show
  1. package/README.md +39 -5
  2. package/dist/providers/openai/index.d.mts +39 -52
  3. package/dist/providers/openai/index.d.ts +39 -52
  4. package/dist/providers/openai/index.js +418 -581
  5. package/dist/providers/openai/index.js.map +1 -1
  6. package/dist/providers/openai/index.mjs +418 -581
  7. package/dist/providers/openai/index.mjs.map +1 -1
  8. package/dist/providers/vercel-ai/index.d.mts +48 -107
  9. package/dist/providers/vercel-ai/index.d.ts +48 -107
  10. package/dist/providers/vercel-ai/index.js +344 -494
  11. package/dist/providers/vercel-ai/index.js.map +1 -1
  12. package/dist/providers/vercel-ai/index.mjs +344 -494
  13. package/dist/providers/vercel-ai/index.mjs.map +1 -1
  14. package/package.json +2 -2
package/README.md CHANGED
@@ -302,12 +302,25 @@ Each tool accepts specific parameters. Here are some common ones:
302
302
 
303
303
  ## Error Handling
304
304
 
305
- The tools handle API errors gracefully and will return informative error messages if:
305
+ When a request fails, a tool returns a structured JSON error (instead of `null`) so the model can explain *why* to the user:
306
306
 
307
- - The API key is invalid or missing
308
- - The requested data is not available
309
- - Rate limits are exceeded
310
- - Invalid parameters are provided
307
+ ```json
308
+ { "error": true, "type": "plan-restricted", "message": "This endpoint is not available on your current FMP plan. (403: ...)", "status": 403 }
309
+ ```
310
+
311
+ The `type` field classifies the failure so your agent can react appropriately:
312
+
313
+ | `type` | Meaning |
314
+ | ----------------- | ------------------------------------------------------------ |
315
+ | `plan-restricted` | Endpoint isn't included in your FMP subscription (402/403) |
316
+ | `rate-limit` | FMP quota / rate limit reached (429) |
317
+ | `auth` | Invalid or missing `FMP_API_KEY` (401) |
318
+ | `not-found` | Resource does not exist (404) |
319
+ | `bad-request` | Invalid parameters (400) |
320
+ | `network` | No response from FMP (timeout / offline) |
321
+ | `unknown` | Anything else |
322
+
323
+ 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`.)
311
324
 
312
325
  ## Testing Tools
313
326
 
@@ -335,6 +348,27 @@ const quote = await fmp.quote.getQuote('AAPL');
335
348
  const profile = await fmp.company.getCompanyProfile('AAPL');
336
349
  ```
337
350
 
351
+ ## Architecture
352
+
353
+ Each tool is defined **once**, provider-agnostically, then adapted to each AI SDK:
354
+
355
+ ```
356
+ src/definitions/<category>.ts one FMPToolDefinition per tool: { name, description, inputSchema (Zod), execute }
357
+ src/utils/aisdk-tool-wrapper.ts createTool() → Vercel AI SDK tool
358
+ src/utils/openai-tool-wrapper.ts createOpenAITool() → OpenAI Agents tool
359
+ src/providers/<provider>/index.ts builds that provider's public shape from the shared definitions
360
+ ```
361
+
362
+ A definition's `execute` calls the `fmp-node-api` method and returns `toToolResponse(...)`, which formats the result (or a structured error) for the model. The adapters add logging and error catching; the OpenAI adapter also validates input against the Zod schema.
363
+
364
+ ### Adding a tool
365
+
366
+ 1. Add a `defineTool({ name, description, inputSchema, execute })` to the relevant `src/definitions/<category>.ts` (or create a new category file and register it in `src/definitions/index.ts`).
367
+ 2. Add a one-line individual export to each provider's `index.ts` (`src/providers/vercel-ai/index.ts` and `src/providers/openai/index.ts`). It flows into the category group and `fmpTools` automatically.
368
+ 3. Add a test and run `pnpm --filter fmp-ai-tools test`.
369
+
370
+ Adding a brand-new provider is a single adapter (`src/utils/<provider>-tool-wrapper.ts`) plus a `src/providers/<provider>/index.ts`.
371
+
338
372
  ## License
339
373
 
340
374
  MIT
package/dist/providers/openai/index.d.mts CHANGED
@@ -1,64 +1,51 @@
1
- import * as _openai_agents from '@openai/agents';
2
1
  import { Tool } from '@openai/agents';
3
- import { z } from 'zod';
4
-
5
- declare const getCompanyProfile: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
6
- declare const getCompanySharesFloat: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
7
- declare const getCompanyExecutiveCompensation: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
8
-
9
- declare const getEarningsCalendar: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
10
- declare const getEconomicCalendar: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
11
-
12
- declare const getTreasuryRates: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
13
- declare const getEconomicIndicators: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
14
-
15
- declare const getETFHoldings: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
16
- declare const getETFProfile: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
17
-
18
- declare const getBalanceSheet: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
19
- declare const getIncomeStatement: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
20
- declare const getCashFlowStatement: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
21
- declare const getKeyMetrics: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
22
- declare const getFinancialRatios: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
23
- declare const getEnterpriseValue: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
24
- declare const getCashflowGrowth: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
25
- declare const getIncomeGrowth: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
26
- declare const getBalanceSheetGrowth: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
27
- declare const getFinancialGrowth: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
28
- declare const getEarningsHistorical: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
29
-
30
- declare const getInsiderTrading: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
31
-
32
- declare const getInstitutionalHolders: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
33
-
34
- declare const getMarketPerformance: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
35
- declare const getSectorPerformance: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
36
- declare const getGainers: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
37
- declare const getLosers: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
38
- declare const getMostActive: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
39
-
40
- declare const getStockQuote: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
41
-
42
- declare const getSenateTrading: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
43
- declare const getHouseTrading: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
44
- declare const getSenateTradingByName: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
45
- declare const getHouseTradingByName: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
46
- declare const getSenateTradingRSSFeed: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
47
- declare const getHouseTradingRSSFeed: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
48
-
49
- declare const getMarketCap: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
50
- declare const getStockSplits: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
51
- declare const getDividendHistory: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
52
2
 
3
+ declare const getStockQuote: Tool<unknown>;
4
+ declare const getCompanyProfile: Tool<unknown>;
5
+ declare const getCompanySharesFloat: Tool<unknown>;
6
+ declare const getCompanyExecutiveCompensation: Tool<unknown>;
7
+ declare const getEarningsCalendar: Tool<unknown>;
8
+ declare const getEconomicCalendar: Tool<unknown>;
9
+ declare const getTreasuryRates: Tool<unknown>;
10
+ declare const getEconomicIndicators: Tool<unknown>;
11
+ declare const getETFHoldings: Tool<unknown>;
12
+ declare const getETFProfile: Tool<unknown>;
13
+ declare const getBalanceSheet: Tool<unknown>;
14
+ declare const getIncomeStatement: Tool<unknown>;
15
+ declare const getCashFlowStatement: Tool<unknown>;
16
+ declare const getKeyMetrics: Tool<unknown>;
17
+ declare const getFinancialRatios: Tool<unknown>;
18
+ declare const getEnterpriseValue: Tool<unknown>;
19
+ declare const getCashflowGrowth: Tool<unknown>;
20
+ declare const getIncomeGrowth: Tool<unknown>;
21
+ declare const getBalanceSheetGrowth: Tool<unknown>;
22
+ declare const getFinancialGrowth: Tool<unknown>;
23
+ declare const getEarningsHistorical: Tool<unknown>;
24
+ declare const getInsiderTrading: Tool<unknown>;
25
+ declare const getInstitutionalHolders: Tool<unknown>;
26
+ declare const getMarketPerformance: Tool<unknown>;
27
+ declare const getSectorPerformance: Tool<unknown>;
28
+ declare const getGainers: Tool<unknown>;
29
+ declare const getLosers: Tool<unknown>;
30
+ declare const getMostActive: Tool<unknown>;
31
+ declare const getSenateTrading: Tool<unknown>;
32
+ declare const getHouseTrading: Tool<unknown>;
33
+ declare const getSenateTradingByName: Tool<unknown>;
34
+ declare const getHouseTradingByName: Tool<unknown>;
35
+ declare const getSenateTradingRSSFeed: Tool<unknown>;
36
+ declare const getHouseTradingRSSFeed: Tool<unknown>;
37
+ declare const getMarketCap: Tool<unknown>;
38
+ declare const getStockSplits: Tool<unknown>;
39
+ declare const getDividendHistory: Tool<unknown>;
40
+ declare const quoteTools: Tool<unknown>[];
53
41
  declare const companyTools: Tool<unknown>[];
42
+ declare const financialTools: Tool<unknown>[];
54
43
  declare const calendarTools: Tool<unknown>[];
55
44
  declare const economicTools: Tool<unknown>[];
56
45
  declare const etfTools: Tool<unknown>[];
57
- declare const financialTools: Tool<unknown>[];
58
46
  declare const insiderTools: Tool<unknown>[];
59
47
  declare const institutionalTools: Tool<unknown>[];
60
48
  declare const marketTools: Tool<unknown>[];
61
- declare const quoteTools: Tool<unknown>[];
62
49
  declare const senateHouseTools: Tool<unknown>[];
63
50
  declare const stockTools: Tool<unknown>[];
64
51
  declare const fmpTools: Tool<unknown>[];
package/dist/providers/openai/index.d.ts CHANGED
@@ -1,64 +1,51 @@
1
- import * as _openai_agents from '@openai/agents';
2
1
  import { Tool } from '@openai/agents';
3
- import { z } from 'zod';
4
-
5
- declare const getCompanyProfile: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
6
- declare const getCompanySharesFloat: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
7
- declare const getCompanyExecutiveCompensation: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
8
-
9
- declare const getEarningsCalendar: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
10
- declare const getEconomicCalendar: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
11
-
12
- declare const getTreasuryRates: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
13
- declare const getEconomicIndicators: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
14
-
15
- declare const getETFHoldings: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
16
- declare const getETFProfile: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
17
-
18
- declare const getBalanceSheet: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
19
- declare const getIncomeStatement: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
20
- declare const getCashFlowStatement: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
21
- declare const getKeyMetrics: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
22
- declare const getFinancialRatios: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
23
- declare const getEnterpriseValue: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
24
- declare const getCashflowGrowth: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
25
- declare const getIncomeGrowth: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
26
- declare const getBalanceSheetGrowth: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
27
- declare const getFinancialGrowth: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
28
- declare const getEarningsHistorical: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
29
-
30
- declare const getInsiderTrading: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
31
-
32
- declare const getInstitutionalHolders: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
33
-
34
- declare const getMarketPerformance: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
35
- declare const getSectorPerformance: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
36
- declare const getGainers: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
37
- declare const getLosers: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
38
- declare const getMostActive: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
39
-
40
- declare const getStockQuote: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
41
-
42
- declare const getSenateTrading: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
43
- declare const getHouseTrading: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
44
- declare const getSenateTradingByName: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
45
- declare const getHouseTradingByName: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
46
- declare const getSenateTradingRSSFeed: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
47
- declare const getHouseTradingRSSFeed: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
48
-
49
- declare const getMarketCap: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
50
- declare const getStockSplits: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
51
- declare const getDividendHistory: _openai_agents.FunctionTool<unknown, z.ZodObject<any, z.core.$strip>, string>;
52
2
 
3
+ declare const getStockQuote: Tool<unknown>;
4
+ declare const getCompanyProfile: Tool<unknown>;
5
+ declare const getCompanySharesFloat: Tool<unknown>;
6
+ declare const getCompanyExecutiveCompensation: Tool<unknown>;
7
+ declare const getEarningsCalendar: Tool<unknown>;
8
+ declare const getEconomicCalendar: Tool<unknown>;
9
+ declare const getTreasuryRates: Tool<unknown>;
10
+ declare const getEconomicIndicators: Tool<unknown>;
11
+ declare const getETFHoldings: Tool<unknown>;
12
+ declare const getETFProfile: Tool<unknown>;
13
+ declare const getBalanceSheet: Tool<unknown>;
14
+ declare const getIncomeStatement: Tool<unknown>;
15
+ declare const getCashFlowStatement: Tool<unknown>;
16
+ declare const getKeyMetrics: Tool<unknown>;
17
+ declare const getFinancialRatios: Tool<unknown>;
18
+ declare const getEnterpriseValue: Tool<unknown>;
19
+ declare const getCashflowGrowth: Tool<unknown>;
20
+ declare const getIncomeGrowth: Tool<unknown>;
21
+ declare const getBalanceSheetGrowth: Tool<unknown>;
22
+ declare const getFinancialGrowth: Tool<unknown>;
23
+ declare const getEarningsHistorical: Tool<unknown>;
24
+ declare const getInsiderTrading: Tool<unknown>;
25
+ declare const getInstitutionalHolders: Tool<unknown>;
26
+ declare const getMarketPerformance: Tool<unknown>;
27
+ declare const getSectorPerformance: Tool<unknown>;
28
+ declare const getGainers: Tool<unknown>;
29
+ declare const getLosers: Tool<unknown>;
30
+ declare const getMostActive: Tool<unknown>;
31
+ declare const getSenateTrading: Tool<unknown>;
32
+ declare const getHouseTrading: Tool<unknown>;
33
+ declare const getSenateTradingByName: Tool<unknown>;
34
+ declare const getHouseTradingByName: Tool<unknown>;
35
+ declare const getSenateTradingRSSFeed: Tool<unknown>;
36
+ declare const getHouseTradingRSSFeed: Tool<unknown>;
37
+ declare const getMarketCap: Tool<unknown>;
38
+ declare const getStockSplits: Tool<unknown>;
39
+ declare const getDividendHistory: Tool<unknown>;
40
+ declare const quoteTools: Tool<unknown>[];
53
41
  declare const companyTools: Tool<unknown>[];
42
+ declare const financialTools: Tool<unknown>[];
54
43
  declare const calendarTools: Tool<unknown>[];
55
44
  declare const economicTools: Tool<unknown>[];
56
45
  declare const etfTools: Tool<unknown>[];
57
- declare const financialTools: Tool<unknown>[];
58
46
  declare const insiderTools: Tool<unknown>[];
59
47
  declare const institutionalTools: Tool<unknown>[];
60
48
  declare const marketTools: Tool<unknown>[];
61
- declare const quoteTools: Tool<unknown>[];
62
49
  declare const senateHouseTools: Tool<unknown>[];
63
50
  declare const stockTools: Tool<unknown>[];
64
51
  declare const fmpTools: Tool<unknown>[];