sec-edgar-api 0.2.4 → 0.3.1

package/build/services/ReportRawBuilder/ReportRawBuilder.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var FactFiscalCalculator_1 = require("./FactFiscalCalculator");
+var FactGrouper_1 = require("./FactGrouper");
+var FactRecordBuilder_1 = require("./FactRecordBuilder");
+var FactSplitAdjuster_1 = require("./FactSplitAdjuster");
+/**
+ * Builds ReportRaw objects from company facts. Adjusts for splits and resolves period values.
+ */
+var ReportRawBuilder = /** @class */ (function () {
+    function ReportRawBuilder() {
+        this.factRecordBuilder = new FactRecordBuilder_1.default();
+    }
+    ReportRawBuilder.prototype.createFacts = function (companyFacts, includeNamePrefix) {
+        if (includeNamePrefix === void 0) { includeNamePrefix = false; }
+        return this.factRecordBuilder.createFacts(companyFacts, includeNamePrefix);
+    };
+    ReportRawBuilder.prototype.createFiscalCalculator = function (params) {
+        var facts = params.facts;
+        var fiscalCalculator = new FactFiscalCalculator_1.default();
+        for (var _i = 0, facts_1 = facts; _i < facts_1.length; _i++) {
+            var fact = facts_1[_i];
+            fiscalCalculator.add(fact);
+        }
+        return fiscalCalculator;
+    };
+    ReportRawBuilder.prototype.buildReports = function (params) {
+        var facts = params.facts, reportDates = params.reportDates, splitsProp = params.splits, _a = params.resolvePeriodValues, resolvePeriodValues = _a === void 0 ? true : _a, _b = params.adjustForSplits, adjustForSplits = _b === void 0 ? true : _b;
+        if (facts.length === 0) {
+            return [];
+        }
+        var accessionByYearQuarter = new Map();
+        reportDates === null || reportDates === void 0 ? void 0 : reportDates.forEach(function (params) {
+            var year = params.year, quarter = params.quarter, accn = params.accn;
+            if (accn)
+                accessionByYearQuarter.set("".concat(year, "_").concat(quarter), accn);
+        });
+        var reportsCik = Number(facts[0].cik);
+        var fiscalCalculator = this.createFiscalCalculator({ facts: facts });
+        var factGrouper = new FactGrouper_1.default();
+        var factSplitAdjuster = new FactSplitAdjuster_1.default();
+        // if splits not included in params and need to adjust, extract from facts
+        var splits = adjustForSplits
+            ? splitsProp !== null && splitsProp !== void 0 ? splitsProp : factSplitAdjuster.getSplits({ splitFacts: factSplitAdjuster.filterSplitFacts({ facts: facts }) })
+            : splitsProp;
+        var _c = factGrouper.buildFactGroupsByReportKey({
+            facts: facts,
+            cik: reportsCik,
+            fiscalCalculator: fiscalCalculator,
+            resolvePeriodValues: resolvePeriodValues,
+            generateMissingGroups: false,
+            splits: splits,
+        }), factGroupsByReportKey = _c.factGroupsByReportKey, maxYear = _c.maxYear, minYear = _c.minYear;
+        return this.buildReportsFromGroups({
+            factGroupsByReportKey: factGroupsByReportKey,
+            fiscalCalculator: fiscalCalculator,
+            splits: splits,
+            minYear: minYear,
+            maxYear: maxYear,
+            cik: reportsCik,
+        });
+    };
+    ReportRawBuilder.prototype.createReportKey = function (params) {
+        var year = params.year, quarter = params.quarter, isAnnual = params.isAnnual;
+        return "".concat(year, "_").concat(isAnnual ? 'FY' : "Q".concat(quarter));
+    };
+    ReportRawBuilder.prototype.createReport = function (params) {
+        var _a;
+        var group = params.group, isAnnual = params.isAnnual, splitDate = params.splitDate, splitRatio = params.splitRatio, cik = params.cik;
+        var fiscalPeriod = isAnnual ? 'FY' : "Q".concat(group.quarter);
+        var accessionNoHyphen = (_a = group.accn) === null || _a === void 0 ? void 0 : _a.replace(/-/g, '');
+        var url = group.accn
+            ? "https://www.sec.gov/Archives/edgar/data/".concat(cik, "/").concat(accessionNoHyphen, "/").concat(group.accn, ".txt")
+            : null;
+        return {
+            cik: cik,
+            url: url,
+            dateFiled: group.reportFiled,
+            dateReport: group.reportEnd,
+            fiscalPeriod: fiscalPeriod,
+            fiscalYear: group.fiscalYear,
+            splitDate: splitDate !== null && splitDate !== void 0 ? splitDate : null,
+            splitRatio: splitRatio !== null && splitRatio !== void 0 ? splitRatio : null,
+        };
+    };
+    ReportRawBuilder.prototype.round = function (value) {
+        var multiplier = 1000000;
+        return typeof value === 'number' ? Math.round(value * multiplier) / multiplier : value;
+    };
+    ReportRawBuilder.prototype.buildReportsFromGroups = function (params) {
+        var _this = this;
+        var factGroupsByReportKey = params.factGroupsByReportKey, minYear = params.minYear, maxYear = params.maxYear, cik = params.cik, splits = params.splits, fiscalCalculator = params.fiscalCalculator;
+        var splitByFiscals = new Map();
+        var reportByKey = new Map();
+        splits === null || splits === void 0 ? void 0 : splits.forEach(function (split) {
+            var _a = fiscalCalculator.getFiscalYearQuarter({ dateStr: split.endLast }), quarter = _a.quarter, year = _a.year;
+            splitByFiscals.set("".concat(year, "_").concat(quarter), split);
+        });
+        factGroupsByReportKey.forEach(function (groups) {
+            var _a, _b, _c, _d, _e, _f;
+            var groupWithDates = groups.find(function (g) { return g.reportEnd; });
+            if (!groupWithDates)
+                return;
+            var split = splitByFiscals.get("".concat(groupWithDates.fiscalYear, "_").concat(groupWithDates.quarter));
+            var splitDate = (_a = split === null || split === void 0 ? void 0 : split.endLast) !== null && _a !== void 0 ? _a : null;
+            var splitRatio = (_b = split === null || split === void 0 ? void 0 : split.splitRatio) !== null && _b !== void 0 ? _b : null;
+            var quarter = groupWithDates.quarter;
+            var reportPeriod = _this.createReport({
+                group: groupWithDates,
+                cik: cik,
+                isAnnual: false,
+                splitDate: splitDate,
+                splitRatio: splitRatio,
+            });
+            var reportKeyPeriod = _this.createReportKey({
+                year: reportPeriod.fiscalYear,
+                quarter: quarter,
+                isAnnual: false,
+            });
+            for (var _i = 0, groups_1 = groups; _i < groups_1.length; _i++) {
+                var group = groups_1[_i];
+                var value = (_d = (_c = group.valuePeriodResolved) !== null && _c !== void 0 ? _c : group.valuePeriodFirst) !== null && _d !== void 0 ? _d : 0;
+                reportPeriod[group.name] = _this.round(value);
+            }
+            reportByKey.set(reportKeyPeriod, reportPeriod);
+            if (quarter !== 4)
+                return;
+            var reportAnnual = _this.createReport({
+                group: groupWithDates,
+                cik: cik,
+                isAnnual: true,
+                splitDate: splitDate,
+                splitRatio: splitRatio,
+            });
+            var reportKeyAnnual = "".concat(reportAnnual.fiscalYear, "_").concat(reportAnnual.fiscalPeriod);
+            for (var _g = 0, groups_2 = groups; _g < groups_2.length; _g++) {
+                var group = groups_2[_g];
+                var value = (_f = (_e = group.valueTrailingResolved) !== null && _e !== void 0 ? _e : group.valueTrailingFirst) !== null && _f !== void 0 ? _f : 0;
+                reportAnnual[group.name] = _this.round(value);
+            }
+            reportByKey.set(reportKeyAnnual, reportAnnual);
+        });
+        var reports = [];
+        for (var year = minYear; year <= maxYear; year++) {
+            for (var quarter = 1; quarter <= 5; quarter++) {
+                var isAnnual = quarter === 5;
+                var reportKey = this.createReportKey({ year: year, quarter: isAnnual ? 4 : quarter, isAnnual: isAnnual });
+                var report = reportByKey.get(reportKey);
+                if (report) {
+                    reports.push(report);
+                }
+            }
+        }
+        return reports;
+    };
+    return ReportRawBuilder;
+}());
+exports.default = ReportRawBuilder;

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

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

package/build/services/ReportRawBuilder/index.js

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

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

@@ -1,4 +1,4 @@
-import { CompanyFactFrame, CompanyFactListData, CompanyTickerItem, FieldDataResponse, Form10KData, Form13GData, Form4Data, FormDef14aData, MultiCompanyFactFrame, ReportRaw, ReportTranslated } from '../../types';
+import { CompanyFactFrame, CompanyFactListData, CompanyTickerItem, DailyFilingFormType, FieldDataResponse, Form10KData, Form13GData, Form4Data, FormDef14aData, MultiCompanyFactFrame, ReportRaw, ReportTranslated } from '../../types';
 import { FilingListDetails, FilingListItemTranslated, SubmissionList } from '../../types/submission.type';
 import { IClient } from '../Client';
 import DocumentParser from '../DocumentParser';
@@ -25,11 +25,19 @@ export interface GetSymbolParams {
     /** symbol or cik */
     symbol: string | number;
 }
-export interface GetReportsParams {
+export interface GetReportsRawParams {
+    symbol: string | number;
+    includeNamePrefix?: boolean;
+    adjustForSplits?: boolean;
+    resolvePeriodValues?: boolean;
+}
+export interface GetReportsParams extends Omit<GetReportsRawParams, 'includeNamePrefix'> {
     /** symbol or cik */
     symbol: string | number;
     withWrapper?: boolean;
     usePropertyResolver?: boolean;
+    adjustForSplits?: boolean;
+    resolvePeriodValues?: boolean;
 }
 export interface GetFactParams {
     /** symbol or cik */
@@ -135,10 +143,9 @@ export default class SecEdgarApi {
      */
     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.
+     * Parses reports from company facts.
      */
-    getReportsRaw(params: GetSymbolParams): Promise<ReportRaw[]>;
+    getReportsRaw(params: GetReportsRawParams): Promise<ReportRaw[]>;
     /**
      * Gets a list of all tickers and CIKs from `https://www.sec.gov/files/company_tickers.json`
      *
@@ -226,5 +233,25 @@ export default class SecEdgarApi {
      * ```
      */
     createRequestProxyStatement(params: CreateRequestWrapperParams): SubmissionRequestWrapper<FormDef14aData>;
+    /**
+     * Gets list of latest filings.
+     *
+     * @see https://www.sec.gov/edgar/searchedgar/currentevents
+     */
+    getCurrentFilingsDaily(params?: {
+        formType?: DailyFilingFormType;
+        lookbackDays?: number;
+    }): Promise<{
+        date: string;
+        matchCount: number;
+        totalCount: number;
+        entries: {
+            accessionNumber: string;
+            form: string;
+            companyCik: number;
+            companyName: string;
+            filedDate: string;
+        }[];
+    }>;
 }
 export {};

package/build/services/SecEdgarApi/SecEdgarApi.js

@@ -1,4 +1,15 @@
 "use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
 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) {
@@ -251,33 +262,39 @@ var SecEdgarApi = /** @class */ (function () {
      */
     SecEdgarApi.prototype.getReports = function (params) {
         return __awaiter(this, void 0, void 0, function () {
-            var symbol, _a, withWrapper, _b, usePropertyResolver, facts, reports;
+            var _a, withWrapper, _b, usePropertyResolver, reportsRaw, reports;
             return __generator(this, function (_c) {
                 switch (_c.label) {
                     case 0:
-                        symbol = params.symbol, _a = params.withWrapper, withWrapper = _a === void 0 ? false : _a, _b = params.usePropertyResolver, usePropertyResolver = _b === void 0 ? true : _b;
-                        return [4 /*yield*/, this.getFacts({ symbol: symbol })];
+                        _a = params.withWrapper, withWrapper = _a === void 0 ? false : _a, _b = params.usePropertyResolver, usePropertyResolver = _b === void 0 ? true : _b;
+                        return [4 /*yield*/, this.getReportsRaw(__assign(__assign({}, params), { includeNamePrefix: false }))];
                     case 1:
-                        facts = _c.sent();
-                        reports = this.reportParser.parseReports(facts, usePropertyResolver);
+                        reportsRaw = _c.sent();
+                        reports = this.reportParser.parseReportsFromRaw({ reportsRaw: reportsRaw, usePropertyResolver: usePropertyResolver });
                         return [2 /*return*/, withWrapper ? reports : reports.map(function (report) { return report.getReport(); })];
                 }
             });
         });
     };
     /**
-     * Parses reports from company facts. Calculates missing properties and uses a single interface
-     * for all reports.
+     * Parses reports from company facts.
      */
     SecEdgarApi.prototype.getReportsRaw = function (params) {
         return __awaiter(this, void 0, void 0, function () {
-            var facts;
-            return __generator(this, function (_a) {
-                switch (_a.label) {
-                    case 0: return [4 /*yield*/, this.getFacts(params)];
+            var symbol, _a, includeNamePrefix, _b, adjustForSplits, _c, resolvePeriodValues, companyFacts, reports;
+            return __generator(this, function (_d) {
+                switch (_d.label) {
+                    case 0:
+                        symbol = params.symbol, _a = params.includeNamePrefix, includeNamePrefix = _a === void 0 ? false : _a, _b = params.adjustForSplits, adjustForSplits = _b === void 0 ? true : _b, _c = params.resolvePeriodValues, resolvePeriodValues = _c === void 0 ? true : _c;
+                        return [4 /*yield*/, this.getFacts({ symbol: symbol })];
                     case 1:
-                        facts = _a.sent();
-                        return [2 /*return*/, this.reportParser.parseReportsRaw(facts)];
+                        companyFacts = _d.sent();
+                        reports = this.reportParser.parseReportsRaw(companyFacts, {
+                            adjustForSplits: adjustForSplits,
+                            resolvePeriodValues: resolvePeriodValues,
+                            includeNamePrefix: includeNamePrefix,
+                        });
+                        return [2 /*return*/, reports];
                 }
             });
         });
@@ -478,6 +495,41 @@ var SecEdgarApi = /** @class */ (function () {
         }); };
         return new RequestWrapper_1.default({ submissions: submissions, options: options, sendRequest: sendRequest });
     };
+    /**
+     * Gets list of latest filings.
+     *
+     * @see https://www.sec.gov/edgar/searchedgar/currentevents
+     */
+    SecEdgarApi.prototype.getCurrentFilingsDaily = function (params) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function () {
+            var _b, _c, formType, _d, lookbackDays, indexByFormType, indexFormType, url, xml;
+            return __generator(this, function (_e) {
+                switch (_e.label) {
+                    case 0:
+                        _b = params !== null && params !== void 0 ? params : {}, _c = _b.formType, formType = _c === void 0 ? 'ALL' : _c, _d = _b.lookbackDays, lookbackDays = _d === void 0 ? 0 : _d;
+                        if (lookbackDays > 5) {
+                            throw new Error("lookbackDays must be <= 5. Received ".concat(lookbackDays));
+                        }
+                        indexByFormType = {
+                            '10-K': 0,
+                            '10-Q': 1,
+                            '14': 2,
+                            '485': 3,
+                            '8-K': 4,
+                            'S-8': 5,
+                            ALL: 6,
+                        };
+                        indexFormType = (_a = indexByFormType[formType]) !== null && _a !== void 0 ? _a : 0;
+                        url = "".concat(this.baseUrlSec, "/cgi-bin/current?q1=").concat(lookbackDays, "&q2=").concat(indexFormType);
+                        return [4 /*yield*/, this.request(url, true)];
+                    case 1:
+                        xml = (_e.sent());
+                        return [2 /*return*/, this.documentParser.parseCurrentFilingsDaily({ xml: xml })];
+                }
+            });
+        });
+    };
     return SecEdgarApi;
 }());
 exports.default = SecEdgarApi;

package/build/types/common.type.d.ts

@@ -1,3 +1,4 @@
+import { FactItem } from './company-facts.type';
 export interface XMLParams {
     xml: string;
 }
@@ -10,3 +11,43 @@ export interface FieldDataResponse<Field extends string = string> {
     fields: Field[];
     data: (string | number)[][];
 }
+export interface SplitData {
+    filedFirst: string;
+    filedLast: string;
+    endFirst: string;
+    endLast: string;
+    splitRatio: number;
+}
+export interface FactGroup {
+    name: string;
+    unit: string;
+    accn: string;
+    reportEnd: string;
+    reportFiled: string;
+    isResolverGenerated: boolean;
+    filedFirst: string;
+    filedLast: string;
+    endFirst: string;
+    endLast: string;
+    values: number[];
+    fiscalYear: number;
+    quarter: number;
+    facts: FactItem[];
+    valueSplitAdjustedPeriod: number | null;
+    valueSplitAdjustedTrailing: number | null;
+    valuePeriodResolved: number | null;
+    valueTrailingResolved: number | null;
+    valuePeriodFirst: number | null;
+    valuePeriodLast: number | null;
+    valueTrailingFirst: number | null;
+    valueTrailingLast: number | null;
+}
+export interface FactItemExtended extends FactItem {
+    period: number;
+    year: number;
+    quarter: number;
+    periodValue: number | null;
+    trailingValue: number | null;
+    splitValue: number | null;
+    splitsApplied: number[];
+}

package/build/types/company-facts.type.d.ts

@@ -1,3 +1,4 @@
+import { FiscalPeriod } from './report-raw.type';
 export interface CompanyFactListData {
     cik: number;
     entityName: string;
@@ -6,11 +7,12 @@ export interface CompanyFactListData {
 export interface CompanyFactList {
     dei: Record<string, CompanyFact>;
     invest?: Record<string, CompanyFact>;
+    srt?: Record<string, CompanyFact>;
     'us-gaap'?: Record<string, CompanyFact>;
 }
 export interface CompanyFact {
-    label: string;
-    description: string;
+    label: string | null;
+    description: string | null;
     units: Record<string, FactValue[]>;
 }
 export interface FactValue {
@@ -51,3 +53,28 @@ export interface MultiCompanyFactFrame {
     pts: number;
     data: MultiCompanyFactFrameItem[];
 }
+export interface FactItem {
+    cik: number | string;
+    end: string;
+    filed: string;
+    name: string;
+    unit: string;
+    value: number | string;
+    start?: string;
+    hasSegments?: boolean;
+    accn?: string;
+    form?: string;
+    fp?: string;
+    frame?: string;
+    fy?: number;
+    /** For XBRL reports only */
+    segments?: {
+        value: string;
+        dimension: string;
+    }[];
+    uuid?: string;
+}
+export interface FactItemWithFiscals extends FactItem {
+    fiscalPeriod: FiscalPeriod;
+    year: number;
+}

package/build/types/parsed-filings.type.d.ts

@@ -93,4 +93,5 @@ export interface FormDef14aData {
     executiveCompensation: ExecutiveCompensation[];
     holders: Holder[];
 }
+export type DailyFilingFormType = '10-K' | '10-Q' | '8-K' | '14' | '485' | 'S-8' | 'ALL';
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "sec-edgar-api",
-    "version": "0.2.4",
+    "version": "0.3.1",
     "description": "Fetch and parse SEC earnings reports and other filings. Useful for financial analysis.",
     "main": "build/index.js",
     "author": "Andrew Evers (https://github.com/andyevers)",

package/build/services/ReportBuilder/FactRecordBuilder.d.ts

@@ -1,10 +0,0 @@
-import { FactItem } from './ReportBuilder';
-import { CompanyFactListData } from '../../types';
-/**
- * Builds an array of fact records.
- */
-export default class FactRecordBuilder {
-    createFacts(data: CompanyFactListData, filterDuplicates?: boolean): {
-        facts: FactItem[];
-    };
-}

package/build/services/ReportBuilder/FactSplitAdjuster.d.ts

@@ -1,50 +0,0 @@
-import { FiscalPeriod } from '../../types/report-raw.type';
-import { FactItemWithFiscals } from './ReportBuilder';
-interface SplitData {
-    end: string;
-    filed: string;
-    value: number;
-    firstFiled: string;
-    fiscalYear: number;
-    fiscalPeriod: FiscalPeriod;
-}
-type FactItemWithFiscalsNumeric = Omit<FactItemWithFiscals, 'cik' | 'value'> & {
-    value: number;
-};
-/**
- * Adjust share-based property values for splits. Checks where the split was applied,
- * and adjusts all previously filed share facts accordingly.
- */
-export default class FactSplitAdjuster {
-    private readonly splitKey;
-    private readonly splitByFiscalYearAmount;
-    private readonly factsByYearQuarterByPropertyName;
-    private readonly factsAnnaulByYearByPropertyName;
-    private readonly resolvedProperties;
-    private sortedSplits;
-    private getMap;
-    private filedFirstLastBySplitKey;
-    add(fact: FactItemWithFiscalsNumeric & {
-        filedLast?: string;
-    }): void;
-    getSplitsAsc(): SplitData[];
-    isSplitProperty(propertyName: string): boolean;
-    addSplitData(data: Omit<SplitData, 'firstFiled'>): void;
-    /**
-     * TODO: Find a more reliable way of checking if the split has already been applied.
-     */
-    private didApplySplit;
-    isSplitAdjustableUnit(unit: string): boolean;
-    isShareRatioUnit(unit: string): boolean;
-    private getSortedFacts;
-    resolveProperty(propertyName: string): void;
-    get(propertyName: string, year: number, fiscalPeriod: FiscalPeriod): number | undefined;
-    forEach(callback: (params: {
-        propertyName: string;
-        year: number;
-        fiscalPeriod: FiscalPeriod;
-        value: number;
-    }) => void): void;
-    private adjustValuesForSplits;
-}
-export {};