fmp-node-api 0.2.3 → 0.2.4-beta.0

package/README.md

@@ -549,7 +549,7 @@ pnpm test:coverage      # Generate coverage report
 Run from the repo root (it builds `fmp-node-types` first so the runner uses fresh schemas):
 
 ```bash
-pnpm test:live                                   # all seeded cases
+pnpm test:live                                   # every manifest case (plan-locked excluded)
 pnpm test:live --category quote,stock            # only these categories
 pnpm test:live --endpoint getQuote               # cases whose name matches
 pnpm test:live --dry-run                         # list cases, make NO API calls
@@ -563,9 +563,9 @@ Each result is classified:
 - **SKIP** — plan-locked (HTTP 402/403) or rate/quota limited (429)
 - **DRIFT** — extra top-level fields, or a non-nullable field came back `null`
 
-Flags: `--delay <ms>` (default 400) paces calls; `--max-calls <n>` (default 50) caps live calls; `--include-locked` also runs cases marked `planLocked`; `--fail-on-drift` makes DRIFT fail the exit code. The runner is sequential and throttled to stay within limited API plans — the first full run doubles as a calibration pass: mark any consistently plan-locked endpoints `planLocked: true` in `scripts/live/manifest.ts` so later default runs skip them. Exits non-zero when any case FAILs.
+Flags: `--delay <ms>` (default 400) paces calls; `--timeout <ms>` (default 30000) is the per-request timeout; `--sample <n>` (default 3) is how many array rows are validated per response; `--max-calls <n>` optionally caps live calls (default: no cap — every selected case runs; a retry can exceed the cap by one); `--include-locked` also runs cases marked `planLocked`; `--fail-on-drift` makes DRIFT fail the exit code. The runner is sequential and throttled to stay within limited API plans (a full run is ~120 calls in ~1–2 minutes) and retries a transient failure (network error / timeout / 5xx) once. Mark any consistently plan-locked endpoints `planLocked: true` in `scripts/live/manifest.ts` so default runs skip them. Exits non-zero when any case FAILs.
 
-> Coverage note: the seeded manifest currently covers the `quote`, `stock`, `financial`, and `market` categories. The classifier logic is unit-tested in `src/__tests__/live/validate.test.ts` (no API key needed).
+> Coverage note: the manifest covers every endpoint category. The classifier logic is unit-tested in `src/__tests__/live/validate.test.ts` (no API key needed).
 
 ## Development
 
@@ -671,7 +671,7 @@ src/
 scripts/
 ├── test-endpoint.ts       # Manual live-API endpoint inspector (raw JSON, one endpoint)
 └── live/                  # Live-API shape-check tool (pnpm test:live)
-    ├── run.ts             # CLI runner (flags, throttle, budget, summary)
+    ├── run.ts             # CLI runner (flags, throttle, retry, summary)
     ├── manifest.ts        # Data-driven registry of cases (endpoint + inputs + schema)
     └── tsconfig.json      # Type-checks the runner (pnpm type-check:live)
 ```

package/dist/index.d.mts

@@ -3625,6 +3625,7 @@ declare class AftermarketEndpoints {
      *
      * Returns the most recent aftermarket trade including price, trade size, and
      * timestamp. Useful for tracking price action outside regular trading hours.
+     * `tradeSize` is `null` when FMP reports no trade size (e.g. after the post-market session closes).
      *
      * @param symbol - The stock symbol (e.g., 'AAPL')
      *

package/dist/index.d.ts

@@ -3625,6 +3625,7 @@ declare class AftermarketEndpoints {
      *
      * Returns the most recent aftermarket trade including price, trade size, and
      * timestamp. Useful for tracking price action outside regular trading hours.
+     * `tradeSize` is `null` when FMP reports no trade size (e.g. after the post-market session closes).
      *
      * @param symbol - The stock symbol (e.g., 'AAPL')
      *

package/dist/types-only.d.mts

@@ -1444,6 +1444,8 @@ declare const FinancialRatiosSchema: z.ZodObject<{
     priceToEarningsRatio: z.ZodNumber;
     priceToEarningsGrowthRatio: z.ZodNumber;
     forwardPriceToEarningsGrowthRatio: z.ZodNumber;
+    priceToEarningsDilutedRatio: z.ZodNumber;
+    priceToEarningsDilutedGrowthRatio: z.ZodNumber;
     priceToBookRatio: z.ZodNumber;
     priceToSalesRatio: z.ZodNumber;
     priceToFreeCashFlowRatio: z.ZodNumber;
@@ -1509,6 +1511,8 @@ declare const FinancialRatiosSchema: z.ZodObject<{
     priceToEarningsRatio: number;
     priceToEarningsGrowthRatio: number;
     forwardPriceToEarningsGrowthRatio: number;
+    priceToEarningsDilutedRatio: number;
+    priceToEarningsDilutedGrowthRatio: number;
     priceToBookRatio: number;
     priceToSalesRatio: number;
     priceToFreeCashFlowRatio: number;
@@ -1574,6 +1578,8 @@ declare const FinancialRatiosSchema: z.ZodObject<{
     priceToEarningsRatio: number;
     priceToEarningsGrowthRatio: number;
     forwardPriceToEarningsGrowthRatio: number;
+    priceToEarningsDilutedRatio: number;
+    priceToEarningsDilutedGrowthRatio: number;
     priceToBookRatio: number;
     priceToSalesRatio: number;
     priceToFreeCashFlowRatio: number;
@@ -2429,6 +2435,8 @@ declare const FinancialRatiosTTMSchema: z.ZodObject<{
     priceToEarningsRatioTTM: z.ZodNumber;
     priceToEarningsGrowthRatioTTM: z.ZodNumber;
     forwardPriceToEarningsGrowthRatioTTM: z.ZodNumber;
+    priceToEarningsDilutedRatioTTM: z.ZodNumber;
+    priceToEarningsDilutedGrowthRatioTTM: z.ZodNumber;
     priceToBookRatioTTM: z.ZodNumber;
     priceToSalesRatioTTM: z.ZodNumber;
     priceToFreeCashFlowRatioTTM: z.ZodNumber;
@@ -2491,6 +2499,8 @@ declare const FinancialRatiosTTMSchema: z.ZodObject<{
     priceToEarningsRatioTTM: number;
     priceToEarningsGrowthRatioTTM: number;
     forwardPriceToEarningsGrowthRatioTTM: number;
+    priceToEarningsDilutedRatioTTM: number;
+    priceToEarningsDilutedGrowthRatioTTM: number;
     priceToBookRatioTTM: number;
     priceToSalesRatioTTM: number;
     priceToFreeCashFlowRatioTTM: number;
@@ -2552,6 +2562,8 @@ declare const FinancialRatiosTTMSchema: z.ZodObject<{
     priceToEarningsRatioTTM: number;
     priceToEarningsGrowthRatioTTM: number;
     forwardPriceToEarningsGrowthRatioTTM: number;
+    priceToEarningsDilutedRatioTTM: number;
+    priceToEarningsDilutedGrowthRatioTTM: number;
     priceToBookRatioTTM: number;
     priceToSalesRatioTTM: number;
     priceToFreeCashFlowRatioTTM: number;
@@ -3293,28 +3305,28 @@ declare const MutualFundHoldingSchema: z.ZodObject<{
 type MutualFundHolding = z.infer<typeof MutualFundHoldingSchema>;
 
 declare const NewsSchema: z.ZodObject<{
-    symbol: z.ZodString;
+    symbol: z.ZodNullable<z.ZodString>;
     publishedDate: z.ZodString;
     publisher: z.ZodString;
     title: z.ZodString;
-    image: z.ZodString;
+    image: z.ZodNullable<z.ZodString>;
     site: z.ZodString;
     text: z.ZodString;
     url: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    symbol: string;
+    symbol: string | null;
     title: string;
     url: string;
-    image: string;
+    image: string | null;
     publishedDate: string;
     publisher: string;
     site: string;
     text: string;
 }, {
-    symbol: string;
+    symbol: string | null;
     title: string;
     url: string;
-    image: string;
+    image: string | null;
     publishedDate: string;
     publisher: string;
     site: string;
@@ -3920,6 +3932,7 @@ declare const ScreenerSchema: z.ZodObject<{
     price: z.ZodNumber;
     lastAnnualDividend: z.ZodNullable<z.ZodNumber>;
     volume: z.ZodNumber;
+    avgVolume: z.ZodNumber;
     exchange: z.ZodString;
     exchangeShortName: z.ZodString;
     country: z.ZodString;
@@ -3940,6 +3953,7 @@ declare const ScreenerSchema: z.ZodObject<{
     isEtf: boolean;
     isActivelyTrading: boolean;
     isFund: boolean;
+    avgVolume: number;
     exchangeShortName: string;
     lastAnnualDividend: number | null;
 }, {
@@ -3956,6 +3970,7 @@ declare const ScreenerSchema: z.ZodObject<{
     isEtf: boolean;
     isActivelyTrading: boolean;
     isFund: boolean;
+    avgVolume: number;
     exchangeShortName: string;
     lastAnnualDividend: number | null;
 }>;
@@ -4312,6 +4327,7 @@ type TechnicalIndicator = z.infer<typeof TechnicalIndicatorSchema>;
 
 declare const SenateTradingResponseSchema: z.ZodObject<{
     symbol: z.ZodString;
+    senateID: z.ZodString;
     disclosureDate: z.ZodString;
     transactionDate: z.ZodString;
     firstName: z.ZodString;
@@ -4333,6 +4349,7 @@ declare const SenateTradingResponseSchema: z.ZodObject<{
     transactionDate: string;
     owner: string;
     office: string;
+    senateID: string;
     disclosureDate: string;
     firstName: string;
     lastName: string;
@@ -4349,6 +4366,7 @@ declare const SenateTradingResponseSchema: z.ZodObject<{
     transactionDate: string;
     owner: string;
     office: string;
+    senateID: string;
     disclosureDate: string;
     firstName: string;
     lastName: string;
@@ -4361,6 +4379,7 @@ declare const SenateTradingResponseSchema: z.ZodObject<{
 }>;
 declare const HouseTradingResponseSchema: z.ZodObject<{
     symbol: z.ZodString;
+    senateID: z.ZodString;
     disclosureDate: z.ZodString;
     transactionDate: z.ZodString;
     firstName: z.ZodString;
@@ -4382,6 +4401,7 @@ declare const HouseTradingResponseSchema: z.ZodObject<{
     transactionDate: string;
     owner: string;
     office: string;
+    senateID: string;
     disclosureDate: string;
     firstName: string;
     lastName: string;
@@ -4398,6 +4418,7 @@ declare const HouseTradingResponseSchema: z.ZodObject<{
     transactionDate: string;
     owner: string;
     office: string;
+    senateID: string;
     disclosureDate: string;
     firstName: string;
     lastName: string;
@@ -4410,6 +4431,7 @@ declare const HouseTradingResponseSchema: z.ZodObject<{
 }>;
 declare const SenateHouseTradingByNameResponseSchema: z.ZodObject<{
     symbol: z.ZodString;
+    senateID: z.ZodString;
     disclosureDate: z.ZodString;
     transactionDate: z.ZodString;
     firstName: z.ZodString;
@@ -4431,6 +4453,7 @@ declare const SenateHouseTradingByNameResponseSchema: z.ZodObject<{
     transactionDate: string;
     owner: string;
     office: string;
+    senateID: string;
     disclosureDate: string;
     firstName: string;
     lastName: string;
@@ -4447,6 +4470,7 @@ declare const SenateHouseTradingByNameResponseSchema: z.ZodObject<{
     transactionDate: string;
     owner: string;
     office: string;
+    senateID: string;
     disclosureDate: string;
     firstName: string;
     lastName: string;
@@ -4705,18 +4729,18 @@ interface CompaniesPriceListResponse<T> {
 declare const AftermarketTradeSchema: z.ZodObject<{
     symbol: z.ZodString;
     price: z.ZodNumber;
-    tradeSize: z.ZodNumber;
+    tradeSize: z.ZodNullable<z.ZodNumber>;
     timestamp: z.ZodNumber;
 }, "strip", z.ZodTypeAny, {
     symbol: string;
     price: number;
     timestamp: number;
-    tradeSize: number;
+    tradeSize: number | null;
 }, {
     symbol: string;
     price: number;
     timestamp: number;
-    tradeSize: number;
+    tradeSize: number | null;
 }>;
 type AftermarketTrade = z.infer<typeof AftermarketTradeSchema>;
 declare const AftermarketQuoteSchema: z.ZodObject<{

package/dist/types-only.d.ts

@@ -1444,6 +1444,8 @@ declare const FinancialRatiosSchema: z.ZodObject<{
     priceToEarningsRatio: z.ZodNumber;
     priceToEarningsGrowthRatio: z.ZodNumber;
     forwardPriceToEarningsGrowthRatio: z.ZodNumber;
+    priceToEarningsDilutedRatio: z.ZodNumber;
+    priceToEarningsDilutedGrowthRatio: z.ZodNumber;
     priceToBookRatio: z.ZodNumber;
     priceToSalesRatio: z.ZodNumber;
     priceToFreeCashFlowRatio: z.ZodNumber;
@@ -1509,6 +1511,8 @@ declare const FinancialRatiosSchema: z.ZodObject<{
     priceToEarningsRatio: number;
     priceToEarningsGrowthRatio: number;
     forwardPriceToEarningsGrowthRatio: number;
+    priceToEarningsDilutedRatio: number;
+    priceToEarningsDilutedGrowthRatio: number;
     priceToBookRatio: number;
     priceToSalesRatio: number;
     priceToFreeCashFlowRatio: number;
@@ -1574,6 +1578,8 @@ declare const FinancialRatiosSchema: z.ZodObject<{
     priceToEarningsRatio: number;
     priceToEarningsGrowthRatio: number;
     forwardPriceToEarningsGrowthRatio: number;
+    priceToEarningsDilutedRatio: number;
+    priceToEarningsDilutedGrowthRatio: number;
     priceToBookRatio: number;
     priceToSalesRatio: number;
     priceToFreeCashFlowRatio: number;
@@ -2429,6 +2435,8 @@ declare const FinancialRatiosTTMSchema: z.ZodObject<{
     priceToEarningsRatioTTM: z.ZodNumber;
     priceToEarningsGrowthRatioTTM: z.ZodNumber;
     forwardPriceToEarningsGrowthRatioTTM: z.ZodNumber;
+    priceToEarningsDilutedRatioTTM: z.ZodNumber;
+    priceToEarningsDilutedGrowthRatioTTM: z.ZodNumber;
     priceToBookRatioTTM: z.ZodNumber;
     priceToSalesRatioTTM: z.ZodNumber;
     priceToFreeCashFlowRatioTTM: z.ZodNumber;
@@ -2491,6 +2499,8 @@ declare const FinancialRatiosTTMSchema: z.ZodObject<{
     priceToEarningsRatioTTM: number;
     priceToEarningsGrowthRatioTTM: number;
     forwardPriceToEarningsGrowthRatioTTM: number;
+    priceToEarningsDilutedRatioTTM: number;
+    priceToEarningsDilutedGrowthRatioTTM: number;
     priceToBookRatioTTM: number;
     priceToSalesRatioTTM: number;
     priceToFreeCashFlowRatioTTM: number;
@@ -2552,6 +2562,8 @@ declare const FinancialRatiosTTMSchema: z.ZodObject<{
     priceToEarningsRatioTTM: number;
     priceToEarningsGrowthRatioTTM: number;
     forwardPriceToEarningsGrowthRatioTTM: number;
+    priceToEarningsDilutedRatioTTM: number;
+    priceToEarningsDilutedGrowthRatioTTM: number;
     priceToBookRatioTTM: number;
     priceToSalesRatioTTM: number;
     priceToFreeCashFlowRatioTTM: number;
@@ -3293,28 +3305,28 @@ declare const MutualFundHoldingSchema: z.ZodObject<{
 type MutualFundHolding = z.infer<typeof MutualFundHoldingSchema>;
 
 declare const NewsSchema: z.ZodObject<{
-    symbol: z.ZodString;
+    symbol: z.ZodNullable<z.ZodString>;
     publishedDate: z.ZodString;
     publisher: z.ZodString;
     title: z.ZodString;
-    image: z.ZodString;
+    image: z.ZodNullable<z.ZodString>;
     site: z.ZodString;
     text: z.ZodString;
     url: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    symbol: string;
+    symbol: string | null;
     title: string;
     url: string;
-    image: string;
+    image: string | null;
     publishedDate: string;
     publisher: string;
     site: string;
     text: string;
 }, {
-    symbol: string;
+    symbol: string | null;
     title: string;
     url: string;
-    image: string;
+    image: string | null;
     publishedDate: string;
     publisher: string;
     site: string;
@@ -3920,6 +3932,7 @@ declare const ScreenerSchema: z.ZodObject<{
     price: z.ZodNumber;
     lastAnnualDividend: z.ZodNullable<z.ZodNumber>;
     volume: z.ZodNumber;
+    avgVolume: z.ZodNumber;
     exchange: z.ZodString;
     exchangeShortName: z.ZodString;
     country: z.ZodString;
@@ -3940,6 +3953,7 @@ declare const ScreenerSchema: z.ZodObject<{
     isEtf: boolean;
     isActivelyTrading: boolean;
     isFund: boolean;
+    avgVolume: number;
     exchangeShortName: string;
     lastAnnualDividend: number | null;
 }, {
@@ -3956,6 +3970,7 @@ declare const ScreenerSchema: z.ZodObject<{
     isEtf: boolean;
     isActivelyTrading: boolean;
     isFund: boolean;
+    avgVolume: number;
     exchangeShortName: string;
     lastAnnualDividend: number | null;
 }>;
@@ -4312,6 +4327,7 @@ type TechnicalIndicator = z.infer<typeof TechnicalIndicatorSchema>;
 
 declare const SenateTradingResponseSchema: z.ZodObject<{
     symbol: z.ZodString;
+    senateID: z.ZodString;
     disclosureDate: z.ZodString;
     transactionDate: z.ZodString;
     firstName: z.ZodString;
@@ -4333,6 +4349,7 @@ declare const SenateTradingResponseSchema: z.ZodObject<{
     transactionDate: string;
     owner: string;
     office: string;
+    senateID: string;
     disclosureDate: string;
     firstName: string;
     lastName: string;
@@ -4349,6 +4366,7 @@ declare const SenateTradingResponseSchema: z.ZodObject<{
     transactionDate: string;
     owner: string;
     office: string;
+    senateID: string;
     disclosureDate: string;
     firstName: string;
     lastName: string;
@@ -4361,6 +4379,7 @@ declare const SenateTradingResponseSchema: z.ZodObject<{
 }>;
 declare const HouseTradingResponseSchema: z.ZodObject<{
     symbol: z.ZodString;
+    senateID: z.ZodString;
     disclosureDate: z.ZodString;
     transactionDate: z.ZodString;
     firstName: z.ZodString;
@@ -4382,6 +4401,7 @@ declare const HouseTradingResponseSchema: z.ZodObject<{
     transactionDate: string;
     owner: string;
     office: string;
+    senateID: string;
     disclosureDate: string;
     firstName: string;
     lastName: string;
@@ -4398,6 +4418,7 @@ declare const HouseTradingResponseSchema: z.ZodObject<{
     transactionDate: string;
     owner: string;
     office: string;
+    senateID: string;
     disclosureDate: string;
     firstName: string;
     lastName: string;
@@ -4410,6 +4431,7 @@ declare const HouseTradingResponseSchema: z.ZodObject<{
 }>;
 declare const SenateHouseTradingByNameResponseSchema: z.ZodObject<{
     symbol: z.ZodString;
+    senateID: z.ZodString;
     disclosureDate: z.ZodString;
     transactionDate: z.ZodString;
     firstName: z.ZodString;
@@ -4431,6 +4453,7 @@ declare const SenateHouseTradingByNameResponseSchema: z.ZodObject<{
     transactionDate: string;
     owner: string;
     office: string;
+    senateID: string;
     disclosureDate: string;
     firstName: string;
     lastName: string;
@@ -4447,6 +4470,7 @@ declare const SenateHouseTradingByNameResponseSchema: z.ZodObject<{
     transactionDate: string;
     owner: string;
     office: string;
+    senateID: string;
     disclosureDate: string;
     firstName: string;
     lastName: string;
@@ -4705,18 +4729,18 @@ interface CompaniesPriceListResponse<T> {
 declare const AftermarketTradeSchema: z.ZodObject<{
     symbol: z.ZodString;
     price: z.ZodNumber;
-    tradeSize: z.ZodNumber;
+    tradeSize: z.ZodNullable<z.ZodNumber>;
     timestamp: z.ZodNumber;
 }, "strip", z.ZodTypeAny, {
     symbol: string;
     price: number;
     timestamp: number;
-    tradeSize: number;
+    tradeSize: number | null;
 }, {
     symbol: string;
     price: number;
     timestamp: number;
-    tradeSize: number;
+    tradeSize: number | null;
 }>;
 type AftermarketTrade = z.infer<typeof AftermarketTradeSchema>;
 declare const AftermarketQuoteSchema: z.ZodObject<{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fmp-node-api",
-  "version": "0.2.3",
+  "version": "0.2.4-beta.0",
   "description": "A comprehensive Node.js wrapper for Financial Modeling Prep API",
   "disclaimer": "This package is not affiliated with, endorsed by, or sponsored by Financial Modeling Prep (FMP). This is an independent, community-developed wrapper.",
   "main": "./dist/index.js",
@@ -55,7 +55,7 @@
     "tsx": "^4.7.0",
     "typescript": "^5.3.3",
     "zod": "^3.25.76",
-    "fmp-node-types": "0.2.3"
+    "fmp-node-types": "0.2.4-beta.0"
   },
   "scripts": {
     "build": "tsup",