sec-edgar-api 0.0.1 → 0.0.3

package/README.md

@@ -3,8 +3,134 @@
 Fetch and parse earnings reports and other documents filed with the SEC using the EDGAR API.
 This package is focused on the earnings reports for stock analysis.
 
+## Report Interface
+
+Reports are all returned as a uniform interface:
+
+```TS
+interface ReportTranslated {
+	dateReport: string
+	dateFiled: string
+	fiscalPeriod: FiscalPeriod
+	fiscalYear: number
+	form: string
+	isTTM: boolean
+
+	assetTotal: number | null
+	assetCurrent: number | null
+	assetCurrentCashEquivalents: number | null
+	assetCurrentInvestments: number | null
+	assetCurrentAccountsReceivable: number | null
+	assetCurrentInventory: number | null
+
+	assetNonCurrent: number | null
+	assetNonCurrentPPENet: number | null
+	assetNonCurrentPPEGross: number | null
+	assetNonCurrentInvestments: number | null
+	assetNonCurrentGoodwill: number | null
+	assetNonCurrentIntangibleLessGoodwill: number | null
+
+	liabilityTotal: number | null
+	liabilityCurrent: number | null
+	liabilityCurrentAccountsPayable: number | null
+	liabilityCurrentDebt: number | null
+	liabilityNonCurrent: number | null
+	liabilityNonCurrentDebt: number | null
+
+	equityTotal: number | null
+	equityRetainedEarnings: number | null
+	equityStockPreferred: number | null
+
+	sharesOutstanding: number | null
+	sharesOutstandingDiluted: number | null
+
+	eps: number | null
+	epsDiluted: number | null
+
+	ebit: number | null
+	ebitda: number | null
+
+	profitGross: number | null
+
+	revenueTotal: number | null
+	revenueCost: number | null
+	revenueOperating: number | null
+
+	expenseTotal: number | null
+	expenseOperating: number | null
+	expenseResearchDevelopment: number | null
+	expenseInterest: number | null
+	expenseDepreciation: number | null
+	expenseTax: number | null
+
+	expenseDepreciationAccumulated: number | null
+	expenseStockCompensation: number | null
+	expenseNonCashOther: number | null
+
+	incomeOperating: number | null
+	incomeNet: number | null
+
+	cashFlowFree: number | null
+	cashFlowDividendsPaid: number | null
+	cashFlowDividendsPaidPreferred: number | null
+
+	cashFlowCapex: number | null
+	cashFlowOperating: number | null
+	cashFlowDeferredTax: number | null
+
+	cashFlowWorkingCapitalNonCash: number | null
+}
+```
+
+## Usage
+
+import package contents
+
+```TS
+import { factFileReader, reportParser, secEdgarApi } from 'sec-edgar-api'
+```
+
+You can fetch reports individually directly from the SEC website, (throttled to 10 requests per second)
+
+```TS
+// returns array of ReportWrapper (which implements ReportTranslated)
+const reports = await secEdgarApi.getReports({ symbol: 'AAPL' })
+```
+
+or download all data from the SEC website and read directly from the files so you don't have to worry about rate limiting.
+
+```TS
+const downloadDirectory = './downloads/companyfacts'
+
+// Download companyfacts directory from sec.gov (over 15GB)
+await secEdgarApi.downloadCompanyFactsDirectory({
+    outputDirname: downloadDirectory,
+    onDownloadComplete: () => process.stdout.write('\n'),
+    onChunk: ({ percentComplete, stage }) => {
+        // Write progress bar to console
+        const countBarsComplete = Math.ceil(percentComplete * 30)
+        const barStr = `${'='.repeat(countBarsComplete)}${' '.repeat(30 - countBarsComplete)}`
+        const percentStr = `${(Math.round(percentComplete * 10000) / 100).toFixed(2)}%`
+        const statusStr = stage === 'download' ? 'Downloading...' : 'Unzipping...'
+
+        process.stdout.write(`\r<${barStr}> ${percentStr} ${statusStr}`)
+    },
+})
+
+// read companyfacts directory
+const companyFacts = factFileReader.readFactFile({
+    companyFactsDirname: downloadDirectory,
+    symbol: 'AAPL',
+})
+
+// parse reports (same return value as secEdgarApi.getReports())
+const reports = reportParser.parseReports(companyFacts)
+```
+
 ## Resolvers
 
+**WARNING** Still in testing. Values may not be accurate for all companies since the properties provided in the reports differ.
+
 The main problem with the edgar API is that the property names and data provided are not uniform. You have to deal with companies omitting important data
 in some filings, or using different property keys for the same data point.
 
@@ -25,3 +151,30 @@ Resolvers attempt to get information from each report and output a uniform inter
 | resolveFiscalYearCumulativeProperties | Q1 + Q2 + Q3 + Q4 = FY (for quarterly properties that add to annual)                                                     |
 | resolveQ4FiscalYearMatchingProperties | Q4 = FY (for non-cumulative properties such as sharesOutstanding)                                                        |
 | resolveRevenueTotal                   | revenueCost + profitGross = revenueTotal                                                                                 |
+
+## Contributing
+
+Getting all the properties in a uniform interface accurately is proving to be very difficult due to the differences in all the reports.
+Please contribute if you know how to improve this.
+
+Files for mapping & resolving properties:
+
+-   Mapping properties: `src/util/key-translations.ts`
+-   Resolving properties: `src/services/ReportParser.ts` (add resolvers to the `resolvers/` directory, import to `/resolver/index.ts`, and add to ReportParser.resolveAll)
+
+These are the scripts I used to get keys commonly used across reports, which you can use to add to `key-translations.ts`
+
+```TS
+import { readAllCompanyFactFiles, getPropertyUsageCounts } from './scripts/script-helpers'
+
+const companyFactsList = readAllCompanyFactFiles(path.resolve('./downloads/companyfacts'), 10)
+const propertyUsageCounts = getPropertyUsageCounts(companyFactsList)
+
+fs.writeFileSync('./downloads/property-usage-counts.json', JSON.stringify(propertyUsageCounts, null, 2))
+```
+
+### Resources
+
+-   Validate resolved values: https://finance.yahoo.com/
+-   Financial calculations: https://www.gurufocus.com/
+-   Calculate change in working capital: https://www.oldschoolvalue.com/stock-valuation/change-in-working-capital/

package/build/services/ReportParser/ReportParser.d.ts

@@ -35,6 +35,10 @@ export default class ReportParser {
      * @see https://www.sec.gov/edgar/sec-api-documentation
      */
     parseReportsRaw(companyFactListData: Pick<CompanyFactListData, 'facts'>, options?: ParseReportsOptions): ReportRaw[];
+    /**
+     * parseReportsRaw but removes meta data from the report
+     */
+    parseReportsRawNoMeta(companyFactListData: Pick<CompanyFactListData, 'facts'>, options?: ParseReportsOptions): Record<string, number>[];
     /**
      * Avoids deep nesting logic while iteratating through company facts
      *

package/build/services/ReportParser/ReportParser.js

@@ -53,6 +53,25 @@ var ReportParser = /** @class */ (function () {
     ReportParser.prototype.parseReportsRaw = function (companyFactListData, options) {
         return this.reportRawParser.parseReports(companyFactListData, options);
     };
+    /**
+     * parseReportsRaw but removes meta data from the report
+     */
+    ReportParser.prototype.parseReportsRawNoMeta = function (companyFactListData, options) {
+        var reportsRaw = this.parseReportsRaw(companyFactListData, options);
+        reportsRaw.forEach(function (reportRaw) {
+            var report = reportRaw;
+            delete report.dateFiled;
+            delete report.dateReport;
+            delete report.fiscalPeriod;
+            delete report.fiscalYear;
+            delete report.form;
+            delete report.frame;
+            delete report.isTTM;
+            delete report.reportType;
+            delete report.taxonomy;
+        });
+        return reportsRaw;
+    };
     /**
      * Avoids deep nesting logic while iteratating through company facts
      *

package/build/services/SecEdgarApi/FactsDownloader.js

@@ -65,7 +65,6 @@ var FactsDownloader = /** @class */ (function () {
             var _this = this;
             return __generator(this, function (_b) {
                 outputDirname = params.outputDirname, onChunk = params.onChunk, onDownloadComplete = params.onDownloadComplete, onError = params.onError, onComplete = params.onComplete, _a = params.unzip, unzip = _a === void 0 ? true : _a;
-                // writes download and unzip progress with percentage in terminal if useWriteProgressBar is true
                 return [2 /*return*/, new Promise(function (resolve, reject) { return __awaiter(_this, void 0, void 0, function () {
                         var filename, e_1;
                         return __generator(this, function (_a) {

package/build/services/SecEdgarApi/SecEdgarApi.d.ts

@@ -70,11 +70,14 @@ export default class SecEdgarApi {
      */
     getFactFrame(params: GetFactFrameParams): Promise<MultiCompanyFactFrame>;
     /**
+     * Note: Properties that are not provied from report are calculated an may not be accurate,
+     * verify results finance.yahoo.com (ex: https://finance.yahoo.com/quote/AAPL/financials)
+     *
+     * Please contribute to improve resolving report properties: https://github.com/andyevers/sec-edgar-api
+     *
      * Parses reports from company facts. Calculates missing properties and uses a single interface
      * for all reports. This includes only 10-K and 10-Q annual and quarterly reports. To include
-     * all reports, use getReportsRaw
-     *
-     * Note that calculated properties are estimated if they are not available in the company facts.
+     * all reports, use getReportsRaw.
      */
     getReports(params: GetSymbolParams): Promise<ReportWrapper[]>;
     /**
@@ -86,6 +89,8 @@ export default class SecEdgarApi {
      * Downloads the companyfacts.zip file and extracts the directory containing all company
      * reports available from sec.gov. After downloading, you can use factFileReader and reportParser
      * to get and read reports.
+     *
+     * Note: Over 15GB of data is downloaded and extracted.
      */
     downloadCompanyFactsDirectory(params: DownloadCompanyFactsDirectoryParams): Promise<boolean>;
 }

package/build/services/SecEdgarApi/SecEdgarApi.js

@@ -131,11 +131,14 @@ var SecEdgarApi = /** @class */ (function () {
         });
     };
     /**
+     * Note: Properties that are not provied from report are calculated an may not be accurate,
+     * verify results finance.yahoo.com (ex: https://finance.yahoo.com/quote/AAPL/financials)
+     *
+     * Please contribute to improve resolving report properties: https://github.com/andyevers/sec-edgar-api
+     *
      * Parses reports from company facts. Calculates missing properties and uses a single interface
      * for all reports. This includes only 10-K and 10-Q annual and quarterly reports. To include
-     * all reports, use getReportsRaw
-     *
-     * Note that calculated properties are estimated if they are not available in the company facts.
+     * all reports, use getReportsRaw.
      */
     SecEdgarApi.prototype.getReports = function (params) {
         return __awaiter(this, void 0, void 0, function () {
@@ -171,6 +174,8 @@ var SecEdgarApi = /** @class */ (function () {
      * Downloads the companyfacts.zip file and extracts the directory containing all company
      * reports available from sec.gov. After downloading, you can use factFileReader and reportParser
      * to get and read reports.
+     *
+     * Note: Over 15GB of data is downloaded and extracted.
      */
     SecEdgarApi.prototype.downloadCompanyFactsDirectory = function (params) {
         return __awaiter(this, void 0, void 0, function () {

package/package.json

@@ -1,8 +1,8 @@
 {
     "name": "sec-edgar-api",
-    "version": "0.0.1",
+    "version": "0.0.3",
     "description": "Fetch and parse SEC earnings reports and other filings. Useful for financial analysis.",
-    "main": "index.js",
+    "main": "build/index.js",
     "author": "Andrew Evers (https://github.com/andyevers)",
     "homepage": "https://github.com/andyevers/sec-edgar-api#readme",
     "license": "ISC",
@@ -15,7 +15,8 @@
     },
     "scripts": {
         "test": "jest test",
-        "build": "tsc"
+        "build": "tsc",
+        "publish": "npm run build && npm publish"
     },
     "keywords": [
         "sec",