sec-edgar-api 0.0.3 → 0.0.6

package/build/services/FactsDownloader/Unzipper.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var fs = require("fs");
+var _unzipper = require("unzipper");
+var Unzipper = /** @class */ (function () {
+    function Unzipper(args) {
+        if (args === void 0) { args = { fileManager: fs, unzipper: _unzipper }; }
+        var fileManager = args.fileManager, unzipper = args.unzipper;
+        this.fileManager = fileManager;
+        this.unzipper = unzipper;
+    }
+    Unzipper.prototype.unzip = function (params) {
+        var _this = this;
+        var inputFilename = params.inputFilename, outputDirname = params.outputDirname, onChunk = params.onChunk, onError = params.onError, _a = params.deleteOriginal, deleteOriginal = _a === void 0 ? false : _a;
+        return new Promise(function (resolve, reject) {
+            var file = _this.fileManager.createReadStream(inputFilename);
+            var filesize = _this.fileManager.statSync(inputFilename).size;
+            var unzipped = _this.unzipper.Extract({ path: outputDirname });
+            var lengthCurrent = 0;
+            file.on('data', function (chunk) {
+                lengthCurrent += chunk.length;
+                var percentComplete = lengthCurrent / filesize;
+                onChunk === null || onChunk === void 0 ? void 0 : onChunk({ percentComplete: percentComplete, chunk: chunk });
+            });
+            file.pipe(unzipped);
+            file.on('end', function () {
+                if (deleteOriginal) {
+                    _this.fileManager.unlinkSync(inputFilename);
+                }
+                resolve(true);
+            });
+            file.on('error', function (err) {
+                onError === null || onError === void 0 ? void 0 : onError(err);
+                reject(false);
+            });
+        });
+    };
+    return Unzipper;
+}());
+exports.default = Unzipper;

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

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

package/build/services/FactsDownloader/index.js

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

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

@@ -8,7 +8,7 @@ interface ReportParserArgs {
     propertyResolver?: PropertyResolver;
     keyTranslator?: Record<string, string[]>;
 }
-type TranslateRawReportsCallback<T> = (report: T extends undefined ? ReportTranslated : Record<keyof T, string | number>, reportRaw: ReportRaw, keyTranslator: T) => any;
+declare type TranslateRawReportsCallback<T> = (report: T extends undefined ? ReportTranslated : Record<keyof T, string | number>, reportRaw: ReportRaw, keyTranslator: T) => any;
 /**
  * Takes company facts data from the SEC and translates them to reports as json objects.
  */

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

@@ -1,5 +1,5 @@
 import { ReportTranslated } from '../../types';
-type ExtendableReportProxy = {
+declare type ExtendableReportProxy = {
     new (report: ReportTranslated): ReportTranslated;
 };
 /**

package/build/services/ReportParser/ReportWrapper.js

@@ -22,9 +22,8 @@ var ReportTranslatedProxy_1 = require("./ReportTranslatedProxy");
 var ReportWrapper = /** @class */ (function (_super) {
     __extends(ReportWrapper, _super);
     function ReportWrapper(report, reportRaw, reportMap) {
-        var _this = this;
         var _a;
-        _this = _super.call(this, report) || this;
+        var _this = _super.call(this, report) || this;
         _this.report = report;
         _this.reportMap = reportMap !== null && reportMap !== void 0 ? reportMap : new Map();
         _this.reportRaw = reportRaw !== null && reportRaw !== void 0 ? reportRaw : {

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

@@ -5,7 +5,7 @@ interface SplitValueBetweenReportsParams {
     reports: ReportTranslated[];
     roundToPlaces: number;
 }
-export type ExcludeNulls<T> = {
+export declare type ExcludeNulls<T> = {
     [K in keyof T]: Exclude<T[K], null>;
 };
 export declare function getSingleNullKey<T>(obj: T): keyof T | null;

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

@@ -0,0 +1,30 @@
+export interface RequestWrapperOptions {
+    maxRequests?: number;
+}
+export interface SendRequestParams {
+    url: string;
+}
+interface RequestWrapperArgs<T> {
+    urls: string[];
+    options?: RequestWrapperOptions;
+    sendRequest: (params: SendRequestParams) => Promise<T | T[]>;
+}
+export default class RequestWrapper<T> {
+    private results;
+    private readonly options;
+    private readonly urls;
+    private readonly errors;
+    private readonly sendRequest;
+    private requestCount;
+    private isDone;
+    constructor(args: RequestWrapperArgs<T>);
+    setOptions(options: RequestWrapperOptions): void;
+    requestNext(): Promise<T[] | null>;
+    skip(count?: number): void;
+    requestAll(): Promise<T[]>;
+    clearResults(): void;
+    getResults(): T[];
+    getErrors(): string[];
+    getSize(): number;
+}
+export {};

package/build/services/SecEdgarApi/RequestWrapper.js

@@ -0,0 +1,133 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (_) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+var RequestWrapper = /** @class */ (function () {
+    function RequestWrapper(args) {
+        var urls = args.urls, _a = args.options, options = _a === void 0 ? {} : _a, sendRequest = args.sendRequest;
+        this.options = options;
+        this.urls = urls;
+        this.results = [];
+        this.errors = [];
+        this.sendRequest = sendRequest;
+        this.requestCount = 0;
+        this.isDone = (options === null || options === void 0 ? void 0 : options.maxRequests) === 0;
+    }
+    RequestWrapper.prototype.setOptions = function (options) {
+        for (var key in options) {
+            this.options[key] = options[key];
+        }
+    };
+    RequestWrapper.prototype.requestNext = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var _a, maxRequests, url, result, resultArr, e_1, error;
+            var _this = this;
+            return __generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        _a = this.options.maxRequests, maxRequests = _a === void 0 ? Infinity : _a;
+                        if (this.requestCount >= maxRequests || this.isDone)
+                            return [2 /*return*/, null];
+                        url = this.urls[this.requestCount];
+                        this.requestCount++;
+                        if (this.requestCount >= this.urls.length || this.requestCount >= maxRequests) {
+                            this.isDone = true;
+                        }
+                        _b.label = 1;
+                    case 1:
+                        _b.trys.push([1, 3, , 4]);
+                        return [4 /*yield*/, this.sendRequest({ url: url })];
+                    case 2:
+                        result = _b.sent();
+                        resultArr = Array.isArray(result) ? result : [result];
+                        resultArr.forEach(function (result) { return _this.results.push(result); });
+                        return [2 /*return*/, resultArr];
+                    case 3:
+                        e_1 = _b.sent();
+                        error = e_1;
+                        this.errors.push(error.message);
+                        return [3 /*break*/, 4];
+                    case 4: return [2 /*return*/, null];
+                }
+            });
+        });
+    };
+    RequestWrapper.prototype.skip = function (count) {
+        if (count === void 0) { count = 1; }
+        this.requestCount += count;
+    };
+    RequestWrapper.prototype.requestAll = function () {
+        var _a;
+        return __awaiter(this, void 0, void 0, function () {
+            var promises, maxRequests, i, resultsArr, resultsFlat;
+            return __generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        promises = [];
+                        maxRequests = (_a = this.options.maxRequests) !== null && _a !== void 0 ? _a : this.urls.length;
+                        for (i = 0; i < maxRequests; i++) {
+                            promises.push(this.requestNext());
+                        }
+                        return [4 /*yield*/, Promise.all(promises)];
+                    case 1:
+                        resultsArr = _b.sent();
+                        resultsFlat = [];
+                        resultsArr.forEach(function (results) {
+                            results === null || results === void 0 ? void 0 : results.forEach(function (result) { return resultsFlat.push(result); });
+                        });
+                        this.clearResults();
+                        this.results = resultsFlat;
+                        return [2 /*return*/, resultsFlat];
+                }
+            });
+        });
+    };
+    RequestWrapper.prototype.clearResults = function () {
+        this.results = [];
+    };
+    RequestWrapper.prototype.getResults = function () {
+        return this.results;
+    };
+    RequestWrapper.prototype.getErrors = function () {
+        return this.errors;
+    };
+    RequestWrapper.prototype.getSize = function () {
+        return this.urls.length;
+    };
+    return RequestWrapper;
+}());
+exports.default = RequestWrapper;

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

@@ -1,6 +1,6 @@
 import { CompanyFactFrame, CompanyFactListData, MultiCompanyFactFrame } from '../../types';
 import { SubmissionList } from '../../types/submission.type';
-import { IClient } from './Client';
+import { IClient } from '../Client';
 import { IThrottler } from './Throttler';
 interface SecApiArgs {
     throttler: IThrottler;

package/build/services/SecEdgarApi/SecConnector.js

@@ -37,7 +37,7 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 var cik_by_symbol_1 = require("../../util/cik-by-symbol");
-var Client_1 = require("./Client");
+var Client_1 = require("../Client");
 var Throttler_1 = require("./Throttler");
 /**
  * Gets reports from companies filed with the SEC

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

@@ -1,55 +1,107 @@
-import { CompanyFactFrame, CompanyFactListData, MultiCompanyFactFrame, ReportRaw, SubmissionList } from '../../types';
+import { CompanyFactFrame, CompanyFactListData, CompanyTickerItem, FieldDataResponse, Holder, InsiderTransaction, MultiCompanyFactFrame, ReportRaw, ReportTranslated } from '../../types';
+import { FilingListDetails, FilingListItemTranslated, SubmissionList } from '../../types/submission.type';
+import { IClient } from '../Client';
+import DocumentParser from '../DocumentParser';
 import ReportParser from '../ReportParser';
 import { ParseReportsOptions } from '../ReportParser/ReportRawParser';
 import ReportWrapper from '../ReportParser/ReportWrapper';
-import { DownloadCompanyFactsDirectoryParams, IFactsDownloader } from './FactsDownloader';
-import { GetFactFrameParams, GetFactParams, GetSymbolParams, ISecConnector } from './SecConnector';
-interface SecEdgarApiArgs {
-    secConnector: ISecConnector;
+import RequestWrapper from './RequestWrapper';
+import { IThrottler } from './Throttler';
+interface SecApiArgs {
+    throttler: IThrottler;
+    client: IClient;
+    cikBySymbol: Record<string, number>;
     reportParser: ReportParser;
-    factsDownloader: IFactsDownloader;
+    documentParser: DocumentParser;
+}
+export interface CreateRequestWrapperParams {
+    /** symbol or cik */
+    symbol: string | number;
+    filings: FilingListDetails | FilingListItemTranslated[];
+    /** earliest allowed filing date that is allowed to be fetched */
+    cutoffDate?: Date;
+    maxRequests?: number;
+}
+export interface GetSymbolParams {
+    /** symbol or cik */
+    symbol: string | number;
+}
+export interface GetReportsParams {
+    /** symbol or cik */
+    symbol: string | number;
+    withWrapper?: boolean;
+}
+export interface GetFactParams {
+    /** symbol or cik */
+    symbol: string | number;
+    fact: string;
+    taxonomy?: 'us-gaap' | 'dei' | 'invest' | string;
+}
+export interface GetFactFrameParams {
+    fact: string;
+    frame: string;
+    unit?: 'pure' | 'USD' | 'shares' | string;
+    taxonomy?: 'us-gaap' | 'dei' | 'invest' | string;
+}
+export interface GetDocumentXMLParams {
+    /** symbol or cik */
+    symbol: string | number;
+    accessionNumber: string;
+    primaryDocument: string;
+}
+export interface GetSubmissionsParams {
+    /** symbol or cik */
+    symbol: string;
+    includeTranslated?: boolean;
 }
 /**
- * Gets company reports and filings from the SEC EDGAR API
- *
- * Requests are throttled with 120ms delay between requests to avoid rate limiting
+ * Gets reports from companies filed with the SEC
  *
  * @see https://www.sec.gov/edgar/sec-api-documentation
  */
 export default class SecEdgarApi {
-    private readonly reportParser;
-    private readonly secConnector;
-    private readonly factsDownloader;
-    constructor(args?: SecEdgarApiArgs);
+    private readonly baseUrlEdgar;
+    private readonly baseUrlSec;
+    private readonly throttler;
+    private readonly client;
+    readonly cikBySymbol: Record<string, number>;
+    readonly reportParser: ReportParser;
+    readonly documentParser: DocumentParser;
+    constructor(args?: SecApiArgs);
+    private request;
+    private mapFilingListDetails;
+    private getCreateRequestUrls;
+    /**
+     * If symbol is not in cikBySymbol, assume it is a cik. does not make a request
+     */
+    getCikString(symbol: string | number): string;
     /**
-     * endpoint: /submissions/CIK${cik}.json
-     *
      * This JSON data structure contains metadata such as current name, former name,
      * and stock exchanges and ticker symbols of publicly-traded companies. The object’s
      * property path contains at least one year’s of filing or to 1,000 (whichever is more)
      * of the most recent filings in a compact columnar data array. If the entity has
      * additional filings, files will contain an array of additional JSON files and the
      * date range for the filings each one contains.
-     */
-    getSubmissions(params: GetSymbolParams): Promise<SubmissionList>;
-    /**
-     * endpoint /api/xbrl/companyconcept/CIK${cik}/${taxonomy}/${fact}.json
      *
-     * This API returns all the company concepts data for a company into a single API call:
+     * endpoint: `/submissions/CIK${cik}.json`
      */
-    getFacts(params: GetSymbolParams): Promise<CompanyFactListData>;
+    getSubmissions(params: GetSubmissionsParams): Promise<SubmissionList>;
     /**
-     * endpoint /api/xbrl/companyconcept/CIK${cik}/${taxonomy}/${fact}.json
-     *
      * The company-concept API returns all the XBRL disclosures from a single company (CIK)
      * and concept (a taxonomy and tag) into a single JSON file, with a separate array
      * of facts for each units on measure that the company has chosen to disclose
      * (e.g. net profits reported in U.S. dollars and in Canadian dollars).
+     *
+     * endpoint `/api/xbrl/companyconcept/CIK${cik}/${taxonomy}/${fact}.json`
      */
     getFact(params: GetFactParams): Promise<CompanyFactFrame>;
     /**
-     * endpoint /api/xbrl/frames/${taxonomy}/${fact}/${unit}/${frame}.json
+     * Returns all the company concepts data for a company into a single API call:
      *
+     * endpoint `/api/xbrl/companyconcept/CIK${cik}/${taxonomy}/${fact}.json`
+     */
+    getFacts(params: GetSymbolParams): Promise<CompanyFactListData>;
+    /**
      * The xbrl/frames API aggregates one fact for each reporting entity that is last filed
      * that most closely fits the calendrical period requested. This API supports for annual,
      * quarterly and instantaneous data:
@@ -67,6 +119,8 @@ export default class SecEdgarApi {
      * data is assembled by the dates that best align with a calendar quarter or year. Data
      * users should be mindful different reporting start and end dates for facts contained
      * in a frame.
+     *
+     * endpoint `/api/xbrl/frames/${taxonomy}/${fact}/${unit}/${frame}.json`
      */
     getFactFrame(params: GetFactFrameParams): Promise<MultiCompanyFactFrame>;
     /**
@@ -79,19 +133,75 @@ export default class SecEdgarApi {
      * for all reports. This includes only 10-K and 10-Q annual and quarterly reports. To include
      * all reports, use getReportsRaw.
      */
-    getReports(params: GetSymbolParams): Promise<ReportWrapper[]>;
+    getReports<T extends GetReportsParams>(params: T): Promise<T['withWrapper'] extends true ? ReportWrapper[] : ReportTranslated[]>;
     /**
      * Parses reports from company facts. Calculates missing properties and uses a single interface
      * for all reports.
      */
     getReportsRaw(params: GetSymbolParams & ParseReportsOptions): Promise<ReportRaw[]>;
     /**
-     * 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.
+     * Gets a list of all tickers and CIKs from `https://www.sec.gov/files/company_tickers.json`
+     *
+     * Note that they key cik_str is actually a number. To get cik string, you can do `${cik_str}`.padStart(10, '0')
+     */
+    getCompanyTickerList(): Promise<CompanyTickerItem[]>;
+    /**
+     * Gets a list of all tickers and CIKs with exchange and company name from `https://www.sec.gov/files/company_tickers_exchange.json`
+     *
+     * response: { fields: ['cik', 'name', 'ticker', 'exchange'], data: [ [320193,'Apple Inc.','AAPL','Nasdaq'], ... ] }
+     */
+    getCompanyTickerExchangeList(): Promise<FieldDataResponse<'cik' | 'name' | 'ticker' | 'exchange'>>;
+    /**
+     * Gets a list of all mutual funds from `https://www.sec.gov/files/company_tickers_mf.json`
+     *
+     * response: { fields: ['cik','seriesId','classId','symbol'], data: [ [2110,'S000009184','C000024954','LACAX'], ... ] }
+     */
+    getMutualFundList(): Promise<FieldDataResponse<'cik' | 'seriesId' | 'classId' | 'symbol'>>;
+    /**
+     * Gets a raw xml document string. the parameters are found in the submission list response. (response.filings.recent or response.filings.recentTranslated)
+     *
+     * Some form types can be parsed using the DocumentParser such as form 4 (insider transactions) and form 13g (institutional holders)
+     *
+     * endpoint: `https://www.sec.gov/Archives/edgar/data/${cik}/${accessionNumber}/${primaryDocument}`
+     *
+     * @see https://www.sec.gov/forms for a list of form types
+     */
+    getDocumentXML(params: GetDocumentXMLParams): Promise<string>;
+    /**
+     * Gets a raw xml document string. the url is found in the submission list response. (response.filings.recentTranslated.url)
+     *
+     * Some form types can be parsed using the DocumentParser such as form 4 (insider transactions) and form 13g (institutional holders)
+     *
+     * endpoint: `https://www.sec.gov/Archives/edgar/data/${cik}/${accessionNumber}/${primaryDocument}`
+     *
+     * @see https://www.sec.gov/forms for a list of form types
+     */
+    getDocumentXMLByUrl(params: {
+        url: string;
+    }): Promise<string>;
+    /**
+     * Used for getting insider transactions. extracts insider transaction urls from submission list response, and parses the xml doc.
+     *
+     * ```ts
+     * const submissions = await secEdgarApi.getSubmissions({ symbol: 'AAPL' })
+     * const requestWrapper = secEdgarApi.createRequestInsiderTransactions({ symbol: 'AAPL', filings: submissions.filings.recent })
+     *
+     * const transactions1 = await requestWrapper.requestNext() // array of transactions from most recent doc
+     * const transactions2 = await requestWrapper.requestNext() // array of transactions from second most recent doc
+     * ```
+     */
+    createRequestInsiderTransactions(params: CreateRequestWrapperParams): RequestWrapper<InsiderTransaction>;
+    /**
+     * Used for getting institutional holders. extracts holders urls from submission list response, and parses the xml doc.
+     *
+     * ```ts
+     * const submissions = await secEdgarApi.getSubmissions({ symbol: 'AAPL' })
+     * const requestWrapper = secEdgarApi.createRequestHolders({ symbol: 'AAPL', filings: submissions.filings.recent })
      *
-     * Note: Over 15GB of data is downloaded and extracted.
+     * const holders1 = await requestWrapper.requestNext() // array of holders from most recent doc
+     * const holders2 = await requestWrapper.requestNext() // array of holders from second most recent doc
+     * ```
      */
-    downloadCompanyFactsDirectory(params: DownloadCompanyFactsDirectoryParams): Promise<boolean>;
+    createRequestHolders(params: CreateRequestWrapperParams): RequestWrapper<Holder>;
 }
 export {};