sec-edgar-api 0.0.5 → 0.0.6

package/README.md

@@ -1,8 +1,15 @@
-# sec-edgar-api
+# SEC Edgar API
 
 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.
 
+Some main data points available include:
+
+-   Earnings Reports
+-   Insider Transactions
+-   Institutional Holders
+-   Filing History
+
 ## Installation
 
 ```SH
@@ -93,7 +100,7 @@ interface ReportTranslated {
 import package contents
 
 ```TS
-import { factFileReader, reportParser, secEdgarApi } from 'sec-edgar-api'
+import { secEdgarApi } from 'sec-edgar-api'
 ```
 
 You can fetch reports individually directly from the SEC website, (throttled to 10 requests per second)
@@ -103,38 +110,6 @@ You can fetch reports individually directly from the SEC website, (throttled to
 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
-import { factsDownloader } from 'sec-edgar-api/downloader'
-
-const downloadDirectory = './downloads/companyfacts'
-
-// Download companyfacts directory from sec.gov (over 15GB)
-await factsDownloader.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.
@@ -170,17 +145,6 @@ 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/

package/build/index.d.ts

@@ -1,4 +1,3 @@
-import FactFileReader from './services/FactFileReader';
 import ReportParser from './services/ReportParser';
 import SecEdgarApi from './services/SecEdgarApi';
 /**
@@ -6,11 +5,6 @@ import SecEdgarApi from './services/SecEdgarApi';
  * reports as json objects.
  */
 declare const reportParser: ReportParser;
-/**
- * Reads files from the companyfacts directory (which can be downloaded
- * using secEdgarApi.downloadCompanyFacts()).
- */
-declare const factFileReader: FactFileReader;
 /**
  * Gets company reports and filings from the SEC EDGAR API. Requests are
  * throttled with 120ms delay between requests to avoid rate limiting.
@@ -18,4 +12,5 @@ declare const factFileReader: FactFileReader;
  * @see https://www.sec.gov/edgar/sec-api-documentation
  */
 declare const secEdgarApi: SecEdgarApi;
-export { reportParser, factFileReader, secEdgarApi };
+export { reportParser, secEdgarApi };
+export * from './types';

package/build/index.js

@@ -1,7 +1,16 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.secEdgarApi = exports.factFileReader = exports.reportParser = void 0;
-var FactFileReader_1 = require("./services/FactFileReader");
+exports.secEdgarApi = exports.reportParser = void 0;
 var ReportParser_1 = require("./services/ReportParser");
 var SecEdgarApi_1 = require("./services/SecEdgarApi");
 /**
@@ -10,12 +19,6 @@ var SecEdgarApi_1 = require("./services/SecEdgarApi");
  */
 var reportParser = new ReportParser_1.default();
 exports.reportParser = reportParser;
-/**
- * Reads files from the companyfacts directory (which can be downloaded
- * using secEdgarApi.downloadCompanyFacts()).
- */
-var factFileReader = new FactFileReader_1.default();
-exports.factFileReader = factFileReader;
 /**
  * Gets company reports and filings from the SEC EDGAR API. Requests are
  * throttled with 120ms delay between requests to avoid rate limiting.
@@ -24,3 +27,4 @@ exports.factFileReader = factFileReader;
  */
 var secEdgarApi = new SecEdgarApi_1.default();
 exports.secEdgarApi = secEdgarApi;
+__exportStar(require("./types"), exports);

package/build/services/Client/Client.d.ts

@@ -1,7 +1,6 @@
 /// <reference types="node" />
-/// <reference types="node" />
 import { ClientRequest, IncomingMessage, RequestOptions } from 'http';
-type Primitive = string | number | boolean | null | undefined;
+declare type Primitive = string | number | boolean | null | undefined;
 interface HttpClient {
     request: (options: string | URL | RequestOptions, callback?: (res: IncomingMessage) => void) => ClientRequest;
 }

package/build/services/Client/index.js

@@ -1,11 +1,7 @@
 "use strict";
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
 }) : (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     o[k2] = m[k];

package/build/services/DocumentParser/DocumentParser.d.ts

@@ -0,0 +1,15 @@
+import { InsiderTransaction, XMLParams } from '../../types';
+import XMLParser from './XMLParser';
+import parsers from './parsers';
+interface DocumentParserArgs {
+    parser?: XMLParser;
+    parsersByName?: typeof parsers;
+}
+export default class DocumentParser {
+    private readonly parser;
+    private readonly parsersByName;
+    constructor(args?: DocumentParserArgs);
+    parseInsiderTransactions(params: XMLParams): InsiderTransaction[];
+    parseHolders(params: XMLParams): import("../../types").Holder[];
+}
+export {};

package/build/services/DocumentParser/DocumentParser.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var XMLParser_1 = require("./XMLParser");
+var parsers_1 = require("./parsers");
+var DocumentParser = /** @class */ (function () {
+    function DocumentParser(args) {
+        var _a = args !== null && args !== void 0 ? args : {}, _b = _a.parser, parser = _b === void 0 ? new XMLParser_1.default() : _b, _c = _a.parsersByName, parsersByName = _c === void 0 ? parsers_1.default : _c;
+        this.parser = parser;
+        this.parsersByName = parsersByName;
+    }
+    DocumentParser.prototype.parseInsiderTransactions = function (params) {
+        return this.parsersByName.parseForm4(params, this.parser);
+    };
+    DocumentParser.prototype.parseHolders = function (params) {
+        return this.parsersByName.parseForm13g(params, this.parser);
+    };
+    return DocumentParser;
+}());
+exports.default = DocumentParser;

package/build/services/DocumentParser/XMLParser.d.ts

@@ -0,0 +1,25 @@
+interface OnCharacterData {
+    char: string;
+    index: number;
+    path: string;
+    pathOccurrenceCount: number;
+}
+interface Parse2Params {
+    xml: string;
+    onCharacter?: (data: OnCharacterData) => void;
+    onOpenTag?: (data: OnCharacterData) => void;
+    onCloseTag?: (data: OnCharacterData) => void;
+}
+interface IterateTablesParams {
+    xml: string;
+    parentPath?: string;
+    trimSpaces?: boolean;
+}
+export default class XMLParser {
+    iterateXML(params: Parse2Params): string[];
+    /**
+     * Returns text in each table cell mapped by `${table}.${row}.${col}`
+     */
+    getTableTextMap(params: IterateTablesParams): Map<string, string>;
+}
+export {};

package/build/services/DocumentParser/XMLParser.js

@@ -0,0 +1,178 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var XMLParser = /** @class */ (function () {
+    function XMLParser() {
+    }
+    XMLParser.prototype.iterateXML = function (params) {
+        var _a, _b, _c, _d;
+        var xml = params.xml, onCharacter = params.onCharacter, onCloseTag = params.onCloseTag, onOpenTag = params.onOpenTag;
+        var selfEnclosingTags = new Set([
+            'filename',
+            'description',
+            'br',
+            'meta',
+            'link',
+            'img',
+            'input',
+            'hr',
+            'area',
+            'base',
+            'col',
+            'command',
+            'embed',
+            'keygen',
+            'param',
+            'source',
+            'track',
+            'wbr',
+        ]);
+        var pathOccurrenceCountMap = new Map();
+        var curPath = '';
+        var curTag = '';
+        var didStart = false;
+        var pathsArr = [];
+        for (var i = 0; i < xml.length; i++) {
+            var char = xml[i];
+            if (char === '<' && xml[i + 1] !== '/' && xml[i + 1] !== '?' && xml[i + 1] !== '!') {
+                var iOpen = i;
+                didStart = true;
+                i++;
+                var j = 0;
+                var didEndTagName = false;
+                while (xml[i] !== '>') {
+                    didEndTagName =
+                        didEndTagName ||
+                            xml[i] === ' ' ||
+                            xml[i] === '\n' ||
+                            xml[i] === '\r' ||
+                            xml[i] === '\t' ||
+                            xml[i] === '/';
+                    if (!didEndTagName) {
+                        curTag += xml[i].toLowerCase();
+                    }
+                    i++;
+                    j++;
+                    if (j > 1000) {
+                        throw new Error('too many iterations');
+                    }
+                }
+                // map path for non-self-enclosing tags
+                if (!selfEnclosingTags.has(curTag)) {
+                    curPath = "".concat(curPath).concat(curPath.length > 0 ? '.' : '').concat(curTag).toLowerCase();
+                    var pathOccurrenceCount = (_a = pathOccurrenceCountMap.get(curPath)) !== null && _a !== void 0 ? _a : 0;
+                    pathOccurrenceCountMap.set(curPath, pathOccurrenceCount + 1);
+                    pathsArr.push(curPath);
+                    onOpenTag === null || onOpenTag === void 0 ? void 0 : onOpenTag({
+                        char: char,
+                        index: iOpen,
+                        path: curPath,
+                        pathOccurrenceCount: (_b = pathOccurrenceCountMap.get(curPath)) !== null && _b !== void 0 ? _b : 0,
+                    });
+                }
+                curTag = '';
+            }
+            else if (char === '<' && xml[i + 1] === '/') {
+                while (xml[i] !== '>') {
+                    i++;
+                }
+                onCloseTag === null || onCloseTag === void 0 ? void 0 : onCloseTag({
+                    char: char,
+                    index: i,
+                    path: curPath,
+                    pathOccurrenceCount: (_c = pathOccurrenceCountMap.get(curPath)) !== null && _c !== void 0 ? _c : 0,
+                });
+                curPath = curPath.slice(0, curPath.lastIndexOf('.'));
+            }
+            else if (didStart) {
+                onCharacter === null || onCharacter === void 0 ? void 0 : onCharacter({
+                    char: char,
+                    index: i,
+                    path: curPath,
+                    pathOccurrenceCount: (_d = pathOccurrenceCountMap.get(curPath)) !== null && _d !== void 0 ? _d : 0,
+                });
+            }
+        }
+        return pathsArr;
+    };
+    /**
+     * Returns text in each table cell mapped by `${table}.${row}.${col}`
+     */
+    XMLParser.prototype.getTableTextMap = function (params) {
+        var xml = params.xml, parentPath = params.parentPath, _a = params.trimSpaces, trimSpaces = _a === void 0 ? true : _a;
+        var rowPaths = new Set([
+            "".concat(parentPath, ".table.tbody.tr"),
+            "".concat(parentPath, ".table.thead.tr"),
+            "".concat(parentPath, ".table.tfoot.tr"),
+            "".concat(parentPath, ".table.tr"),
+        ]);
+        var colPaths = new Set([
+            "".concat(parentPath, ".table.tbody.tr.td"),
+            "".concat(parentPath, ".table.thead.tr.td"),
+            "".concat(parentPath, ".table.tfoot.tr.td"),
+            "".concat(parentPath, ".table.tr.td"),
+            "".concat(parentPath, ".table.tbody.tr.th"),
+            "".concat(parentPath, ".table.thead.tr.th"),
+            "".concat(parentPath, ".table.tfoot.tr.th"),
+            "".concat(parentPath, ".table.tr.th"),
+        ]);
+        var table = 0;
+        var row = 0;
+        var col = 0;
+        var textByColKey = new Map();
+        var spaceChars = new Set(['\n', '\r', '\t']);
+        this.iterateXML({
+            xml: xml,
+            onOpenTag: function (_a) {
+                var _b;
+                var path = _a.path;
+                var colKey = "".concat(table, ".").concat(row, ".").concat(col);
+                var textCur = (_b = textByColKey.get(colKey)) !== null && _b !== void 0 ? _b : '';
+                var pathLower = path.toLowerCase();
+                if (textCur.trim().length === 0 && col === 0) {
+                    textByColKey.delete(colKey);
+                }
+                var isTable = parentPath ? pathLower === "".concat(parentPath, ".table") : pathLower.endsWith('table');
+                var isRow = parentPath ? rowPaths.has(pathLower) : pathLower.endsWith('tr');
+                var isCol = parentPath
+                    ? colPaths.has(pathLower)
+                    : pathLower.endsWith('td') || pathLower.endsWith('th');
+                if (isTable) {
+                    table++;
+                    col = 0;
+                    row = 0;
+                }
+                else if (isRow) {
+                    row++;
+                    col = 0;
+                }
+                else if (isCol) {
+                    col++;
+                }
+            },
+            onCharacter: function (_a) {
+                var _b;
+                var char = _a.char;
+                char = spaceChars.has(char) ? ' ' : char;
+                var colKey = "".concat(table, ".").concat(row, ".").concat(col);
+                var textCur = (_b = textByColKey.get(colKey)) !== null && _b !== void 0 ? _b : '';
+                if (trimSpaces && char === ' ' && textCur.endsWith(' '))
+                    return;
+                textByColKey.set(colKey, "".concat(textCur).concat(char));
+            },
+            onCloseTag: function () {
+                var _a;
+                var colKey = "".concat(table, ".").concat(row, ".").concat(col);
+                var textCur = (_a = textByColKey.get(colKey)) !== null && _a !== void 0 ? _a : '';
+                if (textCur.trim().length === 0 && col === 0) {
+                    textByColKey.delete(colKey);
+                }
+                else if (!textCur.endsWith(' ')) {
+                    textByColKey.set(colKey, "".concat(textCur, " "));
+                }
+            },
+        });
+        return textByColKey;
+    };
+    return XMLParser;
+}());
+exports.default = XMLParser;

package/build/services/DocumentParser/index.d.ts

@@ -0,0 +1,2 @@
+import DocumentParser from './DocumentParser';
+export default DocumentParser;

package/build/services/DocumentParser/index.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var DocumentParser_1 = require("./DocumentParser");
+exports.default = DocumentParser_1.default;

package/build/services/DocumentParser/parsers/index.d.ts

@@ -0,0 +1,7 @@
+import { parseForm4 } from './parse-form-4';
+import { parseForm13g } from './parse-form-13g';
+declare const parsers: {
+    parseForm4: typeof parseForm4;
+    parseForm13g: typeof parseForm13g;
+};
+export default parsers;

package/build/services/DocumentParser/parsers/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var parse_form_4_1 = require("./parse-form-4");
+var parse_form_13g_1 = require("./parse-form-13g");
+var parsers = {
+    parseForm4: parse_form_4_1.parseForm4,
+    parseForm13g: parse_form_13g_1.parseForm13g,
+};
+exports.default = parsers;

package/build/services/DocumentParser/parsers/parse-form-13g.d.ts

@@ -0,0 +1,8 @@
+import { Holder, XMLParams } from '../../../types';
+import XMLParser from '../XMLParser';
+/**
+ * Form SC 13G - Holders
+ *
+ * example at https://www.sec.gov/Archives/edgar/data/320193/000119312523038262/d382361dsc13ga.htm
+ */
+export declare function parseForm13g(params: XMLParams, xmlParser?: XMLParser): Holder[];

package/build/services/DocumentParser/parsers/parse-form-13g.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseForm13g = void 0;
+var XMLParser_1 = require("../XMLParser");
+/**
+ * Form SC 13G - Holders
+ *
+ * example at https://www.sec.gov/Archives/edgar/data/320193/000119312523038262/d382361dsc13ga.htm
+ */
+function parseForm13g(params, xmlParser) {
+    var _a, _b, _c, _d;
+    if (xmlParser === void 0) { xmlParser = new XMLParser_1.default(); }
+    var xml = params.xml;
+    var textMap = xmlParser.getTableTextMap({ xml: xml });
+    var holders = [];
+    var getKey = function (text) {
+        var keyMap = {
+            'name of reporting': 'name',
+            'names of reporting': 'name',
+            'citizenship or place': 'origin',
+            'sole voting power': 'votingPowerSole',
+            'shared voting power': 'votingPowerShared',
+            'sole dispositive power': 'dispositivePowerSole',
+            'shared dispositive power': 'dispositivePowerShared',
+            'aggregate amount beneficially owned': 'shares',
+            'percent of class': 'percentOfClass',
+            'type of reporting person': 'typeOfReportingPerson',
+        };
+        var textLower = text.toLowerCase();
+        for (var key in keyMap) {
+            if (textLower.includes(key))
+                return keyMap[key];
+        }
+        return null;
+    };
+    var _loop_1 = function (text) {
+        var colName = getKey(text);
+        var isNewHolder = colName === 'name';
+        if (isNewHolder) {
+            if (((_a = holders[holders.length - 1]) === null || _a === void 0 ? void 0 : _a.name) === '') {
+                holders.pop();
+            }
+            holders.push({
+                name: '',
+                origin: '',
+                shares: 0,
+                percentOfClass: '',
+                votingPowerSole: null,
+                votingPowerShared: null,
+                dispositivePowerSole: null,
+                dispositivePowerShared: null,
+                typeOfReportingPerson: null,
+            });
+        }
+        var holder = holders[holders.length - 1];
+        // continue if no colName or if the value is already set
+        if (colName === null || ![0, '', null].includes(holder[colName]))
+            return "continue";
+        var textParts = text.split(' ').filter(function (t) { return t.trim() !== ''; });
+        var colNameIndex = textParts.findIndex(function (t) { return getKey(t) === colName; });
+        var value = (_c = (_b = textParts[colNameIndex + 1]) === null || _b === void 0 ? void 0 : _b.trim()) !== null && _c !== void 0 ? _c : '';
+        switch (colName) {
+            case 'shares':
+                holder.shares = Number(value.replace(/[^0-9]/g, '')) || 0;
+                break;
+            case 'typeOfReportingPerson':
+                holder[colName] = value === '' ? null : value;
+                break;
+            case 'votingPowerSole':
+            case 'votingPowerShared':
+            case 'dispositivePowerSole':
+            case 'dispositivePowerShared':
+                holder[colName] = value.toLowerCase() === 'none' ? null : value;
+                break;
+            default:
+                holder[colName] = value;
+        }
+    };
+    for (var _i = 0, _e = Array.from(textMap.values()); _i < _e.length; _i++) {
+        var text = _e[_i];
+        _loop_1(text);
+    }
+    if (((_d = holders[holders.length - 1]) === null || _d === void 0 ? void 0 : _d.name) === '') {
+        holders.pop();
+    }
+    return holders;
+}
+exports.parseForm13g = parseForm13g;

package/build/services/DocumentParser/parsers/parse-form-4.d.ts

@@ -0,0 +1,8 @@
+import { InsiderTransaction, XMLParams } from '../../../types';
+import XMLParser from '../XMLParser';
+/**
+ * Form 4 - Insider Transactions
+ *
+ * example at https://www.sec.gov/Archives/edgar/data/320193/000032019323000079/xslF345X05/wk-form4_1691533817.xml
+ */
+export declare function parseForm4(params: XMLParams, xmlParser?: XMLParser): InsiderTransaction[];