Add options module

README.md

@@ -65,7 +65,8 @@ recommendationTrend, secFilings, sectorTrend, summaryDetail, summaryProfile,
 symbol, topHoldings, upgradeDowngradeHistory),
 [`search`](./docs/modules/search.md),
 [`recommendationsBySymbol`](./docs/modules/recommendationsBySymbol.md),
-[`trendingSymbols`](./docs/modules/trendingSymbols.md), with more
+[`trendingSymbols`](./docs/modules/trendingSymbols.md),
+[`options`](./docs/modules/options.md), with more
 [coming soon](https://github.com/gadicc/node-yahoo-finance2/issues/8).
 
 Extras: [`quoteCombine`](./docs/other/quoteCombine.md).

docs/README.md

@@ -35,6 +35,7 @@ const result = await yahooFinance.module(query, queryOpts, moduleOpts);
 1. [search](./modules/search.md) - symbol lookup, news and articles.
 1. [recommendationsBySymbol](./modules/recommendationsBySymbol.md) - similar symbols.
 1. [trendingSymbols](./modules/trendingSymbols.md) - symbols trending in a country.
+1. [options](./modules/options.md) - options trading (call/put).
 
 <a name="other"></a>
 ## Other Methods

docs/modules/options.md

@@ -0,0 +1,171 @@
+# options
+
+## Usage:
+
+```js
+import yahooFinance from 'yahoo-finance2';
+const queryOptions = { lang: 'en-US', formatted: false, region: 'US' };
+const result = await yahooFinance.options('AYX', queryOptions);
+```
+Example Result (Arrays are shortened so the docs aren't long):
+```js
+{
+  underlyingSymbol: 'AYX',
+  expirationDates: [
+    new Date('2021-04-16T00:00:00.000Z'),
+    new Date('2021-05-21T00:00:00.000Z'),
+    new Date('2021-06-18T00:00:00.000Z'),
+    new Date('2021-08-20T00:00:00.000Z'),
+    new Date('2021-11-19T00:00:00.000Z'),
+    new Date('2022-01-21T00:00:00.000Z'),
+    new Date('2023-01-20T00:00:00.000Z'),
+  ],
+  strikes: [
+     45,  50,  55,  60,  65,  70,  75,
+     80,  85,  90,  95, 100, 105, 110,
+    115, 120, 125, 130, 135, 140, 145,
+    150, 155, 160, 165, 170
+  ],
+  hasMiniOptions: false,
+  quote: {
+    language: 'en-US',
+    region: 'US',
+    quoteType: 'EQUITY',
+    quoteSourceName: 'Delayed Quote',
+    triggerable: true,
+    currency: 'USD',
+    firstTradeDateMilliseconds: new Date('2017-03-24T13:30:00.000Z'),
+    exchange: 'NYQ',
+    shortName: 'Alteryx, Inc.',
+    longName: 'Alteryx, Inc.',
+    messageBoardId: 'finmb_8548197',
+    exchangeTimezoneName: 'America/New_York',
+    exchangeTimezoneShortName: 'EDT',
+    gmtOffSetMilliseconds: -14400000,
+    market: 'us_market',
+    esgPopulated: false,
+    marketState: 'CLOSED',
+    postMarketChangePercent: 0.34013456,
+    postMarketTime: new Date('2021-03-26T23:56:50.000Z'),
+    postMarketPrice: 82.6,
+    postMarketChange: 0.27999878,
+    regularMarketChange: 0.3199997,
+    regularMarketChangePercent: 0.39024353,
+    regularMarketTime: 1616788802,
+    regularMarketPrice: 82.32,
+    regularMarketDayHigh: 83.7,
+    regularMarketDayRange: { low: 79.71, high: 83.7 },
+    regularMarketDayLow: 79.71,
+    regularMarketVolume: 1275079,
+    regularMarketPreviousClose: 82,
+    bid: 81.66,
+    ask: 82.5,
+    bidSize: 11,
+    askSize: 11,
+    fullExchangeName: 'NYSE',
+    financialCurrency: 'USD',
+    regularMarketOpen: 82.59,
+    averageDailyVolume3Month: 1707374,
+    averageDailyVolume10Day: 1400837,
+    fiftyTwoWeekLowChange: 3.5899963,
+    fiftyTwoWeekLowChangePercent: 0.045598835,
+    fiftyTwoWeekRange: { low: 78.73, high: 185.75 },
+    fiftyTwoWeekHighChange: -103.43,
+    fiftyTwoWeekHighChangePercent: -0.5568237,
+    fiftyTwoWeekLow: 78.73,
+    fiftyTwoWeekHigh: 185.75,
+    earningsTimestamp: new Date('2021-02-09T16:05:05.000Z'),
+    earningsTimestampStart: new Date('2021-05-04T10:59:00.000Z'),
+    earningsTimestampEnd: new Date('2021-05-10T12:00:00.000Z'),
+    epsTrailingTwelveMonths: -0.37,
+    epsForward: 0.51,
+    epsCurrentYear: 0.02,
+    priceEpsCurrentYear: 4116,
+    sharesOutstanding: 54044800,
+    bookValue: 7.144,
+    fiftyDayAverage: 97.982285,
+    fiftyDayAverageChange: -15.662285,
+    fiftyDayAverageChangePercent: -0.15984812,
+    twoHundredDayAverage: 116.20604,
+    twoHundredDayAverageChange: -33.88604,
+    twoHundredDayAverageChangePercent: -0.2916031,
+    marketCap: 5504227840,
+    forwardPE: 161.41177,
+    priceToBook: 11.522956,
+    sourceInterval: 15,
+    exchangeDataDelayedBy: 0,
+    priceHint: 2,
+    tradeable: false,
+    displayName: 'Alteryx',
+    symbol: 'AYX'
+  },
+  options: [
+    {
+      expirationDate: new Date('2021-04-16T00:00:00.000Z'),
+      hasMiniOptions: false,
+      calls: [
+        {
+          contractSymbol: 'AYX210416C00155000',
+          strike: 155,
+          currency: 'USD',
+          lastPrice: 0.13,
+          change: 0,
+          percentChange: 0,
+          volume: 2,
+          openInterest: 5,
+          bid: 0,
+          ask: 0.86,
+          contractSize: 'REGULAR',
+          expiration: new Date('2021-04-16T00:00:00.000Z'),
+          lastTradeDate: new Date('2021-03-22T15:24:10.000Z'),
+          impliedVolatility: 1.3984405078125,
+          inTheMoney: false
+        },
+      ],
+      puts: [
+        {
+          contractSymbol: 'AYX210416P00045000',
+          strike: 45,
+          currency: 'USD',
+          lastPrice: 0.16,
+          change: 0,
+          percentChange: 0,
+          volume: 8,
+          openInterest: 118,
+          bid: 0,
+          ask: 0.32,
+          contractSize: 'REGULAR',
+          expiration: new Date('2021-04-16T00:00:00.000Z'),
+          lastTradeDate: new Date('2021-03-18T14:15:59.000Z'),
+          impliedVolatility: 1.2656286718749998,
+          inTheMoney: false
+        },
+      ]
+    }
+  ]
+}
+```
+
+## API
+
+```js
+await yahooFinance.options(query, queryOptions, moduleOptions);
+```
+
+### Symbol
+
+Symbol name as used by Yahoo (often the stock ticker).  You can find it
+using [autoc](./auto.md) or [search](./search.md).  You can also provide
+an array of symbols, and you'll receive an array of results back.
+
+### Query Options
+
+| Name        | Type   | Default | Description                                                       |
+| ----------- | ------ | ------- | ----------------------------------------------------------------- |
+| `formatted` | number | 5       | The max amount of symbols that can be returned.                   |
+| `lang`      | string | "en-US" |                                                                   |
+| `region`    | string | "US"    |                                                                   |
+
+### Module Options
+
+See [Common Options](../README.md#common-options).

schema.json

@@ -343,6 +343,72 @@
       ],
       "type": "object"
     },
+    "CallOrPut": {
+      "additionalProperties": false,
+      "properties": {
+        "ask": {
+          "yahooFinanceType": "number"
+        },
+        "bid": {
+          "yahooFinanceType": "number"
+        },
+        "change": {
+          "yahooFinanceType": "number"
+        },
+        "contractSize": {
+          "const": "REGULAR",
+          "type": "string"
+        },
+        "contractSymbol": {
+          "type": "string"
+        },
+        "currency": {
+          "type": "string"
+        },
+        "expiration": {
+          "yahooFinanceType": "date"
+        },
+        "impliedVolatility": {
+          "yahooFinanceType": "number"
+        },
+        "inTheMoney": {
+          "type": "boolean"
+        },
+        "lastPrice": {
+          "yahooFinanceType": "number"
+        },
+        "lastTradeDate": {
+          "yahooFinanceType": "date"
+        },
+        "openInterest": {
+          "yahooFinanceType": "number"
+        },
+        "percentChange": {
+          "yahooFinanceType": "number"
+        },
+        "strike": {
+          "yahooFinanceType": "number"
+        },
+        "volume": {
+          "yahooFinanceType": "number"
+        }
+      },
+      "required": [
+        "contractSymbol",
+        "strike",
+        "currency",
+        "lastPrice",
+        "change",
+        "percentChange",
+        "ask",
+        "contractSize",
+        "expiration",
+        "lastTradeDate",
+        "impliedVolatility",
+        "inTheMoney"
+      ],
+      "type": "object"
+    },
     "CashflowStatement": {
       "additionalProperties": false,
       "properties": {
@@ -1971,6 +2037,92 @@
       ],
       "type": "object"
     },
+    "Option": {
+      "additionalProperties": false,
+      "properties": {
+        "calls": {
+          "items": {
+            "$ref": "#/definitions/CallOrPut"
+          },
+          "type": "array"
+        },
+        "expirationDate": {
+          "yahooFinanceType": "date"
+        },
+        "hasMiniOptions": {
+          "type": "boolean"
+        },
+        "puts": {
+          "items": {
+            "$ref": "#/definitions/CallOrPut"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "expirationDate",
+        "hasMiniOptions",
+        "calls",
+        "puts"
+      ],
+      "type": "object"
+    },
+    "OptionsOptions": {
+      "additionalProperties": false,
+      "properties": {
+        "formatted": {
+          "type": "boolean"
+        },
+        "lang": {
+          "type": "string"
+        },
+        "region": {
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "OptionsResult": {
+      "additionalProperties": false,
+      "properties": {
+        "expirationDates": {
+          "items": {
+            "yahooFinanceType": "date"
+          },
+          "type": "array"
+        },
+        "hasMiniOptions": {
+          "type": "boolean"
+        },
+        "options": {
+          "items": {
+            "$ref": "#/definitions/Option"
+          },
+          "type": "array"
+        },
+        "quote": {
+          "$ref": "#/definitions/Quote"
+        },
+        "strikes": {
+          "items": {
+            "yahooFinanceType": "number"
+          },
+          "type": "array"
+        },
+        "underlyingSymbol": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "underlyingSymbol",
+        "expirationDates",
+        "strikes",
+        "hasMiniOptions",
+        "quote",
+        "options"
+      ],
+      "type": "object"
+    },
     "Ownership": {
       "additionalProperties": false,
       "properties": {

src/index-common.ts

@@ -11,6 +11,7 @@ import quoteSummary from "./modules/quoteSummary";
 import search from "./modules/search";
 import recommendationsBySymbol from "./modules/recommendationsBySymbol";
 import trendingSymbols from "./modules/trendingSymbols";
+import optionsModule from "./modules/options";
 
 // other
 import quoteCombine from "./other/quoteCombine";
@@ -30,6 +31,7 @@ export default {
   search,
   recommendationsBySymbol,
   trendingSymbols,
+  options: optionsModule,
 
   // other
   quoteCombine,

src/modules/options.spec.ts

@@ -0,0 +1,20 @@
+import options from "./options";
+import testYf from "../../tests/testYf";
+import { testSymbols } from "../../tests/symbols";
+
+const yf = testYf({ options });
+
+describe("options", () => {
+  it.each(testSymbols)("passes validation for symbol '%s'", async (symbol) => {
+    await yf.options(symbol, undefined, {
+      devel: `trendingSymbols-${symbol}.json`,
+    });
+  });
+  if (process.env.FETCH_DEVEL !== "nocache")
+    it("throws on weird result", () => {
+      const devel = "weirdJsonResult.fake.json";
+      return expect(yf.options("A", {}, { devel })).rejects.toThrow(
+        /^Unexpected result/
+      );
+    });
+});