sec-edgar-api 0.2.1 → 0.2.2

package/build/services/ReportParser/resolvers/resolve-split-ratio.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSplitRatio = void 0;
+function resolveSplitRatio(report) {
+    var _a = report.getReportsFiscalYearByPeriod(), Q1 = _a.Q1, Q2 = _a.Q2, Q3 = _a.Q3, Q4 = _a.Q4;
+    var splitReport = null;
+    // FY will have already been matched with Q4 from resolve-q4-fiscal-year-matching-properties.ts
+    var takenRatios = new Set();
+    for (var _i = 0, _b = [Q4, Q3, Q2, Q1]; _i < _b.length; _i++) {
+        var report_1 = _b[_i];
+        if (!(report_1 === null || report_1 === void 0 ? void 0 : report_1.splitRatio))
+            continue;
+        if (takenRatios.has(report_1.splitRatio)) {
+            report_1.splitRatio = null;
+            continue;
+        }
+        splitReport = report_1;
+        takenRatios.add(report_1.splitRatio);
+    }
+    if (!splitReport)
+        return;
+    var prevReports = [
+        splitReport.getReportOffset(-1, 'QUARTERLY'),
+        splitReport.getReportOffset(-2, 'QUARTERLY'),
+        splitReport.getReportOffset(-3, 'QUARTERLY'),
+        splitReport.getReportOffset(-4, 'QUARTERLY'),
+        splitReport.getReportOffset(-1, 'ANNUAL'),
+    ];
+    prevReports.forEach(function (prevReport) {
+        if (prevReport === splitReport)
+            return;
+        if (prevReport && splitReport && prevReport.splitRatio === splitReport.splitRatio) {
+            prevReport.splitRatio = null;
+        }
+    });
+}
+exports.resolveSplitRatio = resolveSplitRatio;

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

@@ -1,18 +1,16 @@
-import { CompanyFactFrame, CompanyFactListData, CompanyTickerItem, FieldDataResponse, Form10KData, Form13GData, Form4Data, FormDef14aData, MultiCompanyFactFrame, ReportRaw, ReportTranslated } from '../../types';
+import { CompanyFactFrame, CompanyFactListData, CompanyTickerItem, FieldDataResponse, FiscalPeriod, MultiCompanyFactFrame, ReportRaw, ReportTranslated } from '../../types';
 import { FilingListDetails, FilingListItemTranslated, SubmissionList } from '../../types/submission.type';
 import { IClient } from '../Client';
-import DocumentParser from '../DocumentParser';
+import _parsers from '../DocumentParser/parsers';
 import ReportParser from '../ReportParser';
-import { ParseReportsOptions } from '../ReportParser/ReportRawParser';
 import ReportWrapper from '../ReportParser/ReportWrapper';
-import SubmissionRequestWrapper from './RequestWrapper';
 import { IThrottler } from './Throttler';
 interface SecApiArgs {
     throttler: IThrottler;
     client: IClient;
     cikBySymbol: Record<string, number>;
     reportParser: ReportParser;
-    documentParser: DocumentParser;
+    parsers: typeof _parsers;
 }
 export interface CreateRequestWrapperParams {
     /** symbol or cik */
@@ -48,12 +46,7 @@ export interface GetDocumentXMLParams {
     /** symbol or cik */
     symbol: string | number;
     accessionNumber: string;
-    primaryDocument: string;
-}
-export interface GetSubmissionsParams {
-    /** symbol or cik */
-    symbol: string;
-    includeTranslated?: boolean;
+    primaryDocument?: string;
 }
 /**
  * Gets reports from companies filed with the SEC
@@ -67,11 +60,12 @@ export default class SecEdgarApi {
     private readonly client;
     readonly cikBySymbol: Record<string, number>;
     readonly reportParser: ReportParser;
-    readonly documentParser: DocumentParser;
+    private readonly parsers;
     constructor(args?: SecApiArgs);
     private request;
     private mapFilingListDetails;
-    private getCreateRequestSubmissions;
+    private filterSubmissionsInFiscalPeriodAsc;
+    private extractSubmissionsWithXml;
     /**
      * If symbol is not in cikBySymbol, assume it is a cik. does not make a request
      */
@@ -86,7 +80,7 @@ export default class SecEdgarApi {
      *
      * endpoint: `/submissions/CIK${cik}.json`
      */
-    getSubmissions(params: GetSubmissionsParams): Promise<SubmissionList>;
+    getSubmissions(params: GetSymbolParams): Promise<SubmissionList>;
     /**
      * 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
@@ -139,7 +133,7 @@ export default class SecEdgarApi {
      * Parses reports from company facts. Calculates missing properties and uses a single interface
      * for all reports.
      */
-    getReportsRaw(params: GetSymbolParams & ParseReportsOptions): Promise<ReportRaw[]>;
+    getReportsRaw(params: GetSymbolParams): Promise<ReportRaw[]>;
     /**
      * Gets a list of all tickers and CIKs from `https://www.sec.gov/files/company_tickers.json`
      *
@@ -159,7 +153,8 @@ export default class SecEdgarApi {
      */
     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)
+     * 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)
      *
@@ -181,51 +176,94 @@ export default class SecEdgarApi {
         url: string;
     }): Promise<string>;
     /**
-     * Used for getting insider transactions. extracts insider transaction urls from submission list response, and parses the xml doc.
+     * Used for getting security holdings.
+     *
+     * Forms: 13F, 13F/A, 13F-HR, 13F-HR/A
      *
-     * ```ts
-     * const submissions = await secEdgarApi.getSubmissions({ symbol: 'AAPL' })
-     * const requestWrapper = secEdgarApi.createRequestInsiderTransactions({ symbol: 'AAPL', filings: submissions.filings.recent })
+     * Extracts holdings urls from submission list response, and parses the xml doc.
      *
-     * const transactions1 = (await requestWrapper.requestNext()).result.transactions // array of transactions from most recent doc
-     * const transactions2 = (await requestWrapper.requestNext()).result.transactions // array of transactions from second most recent doc
-     * ```
+     * Sends 2 requests by default, 1 request if submissions is provided, and 0 requests if documentXml is provided.
+     *
+     * WARNING: XML and HTML docs can be formatted differently and is prone to innacuracies.
      */
-    createRequestInsiderTransactions(params: CreateRequestWrapperParams): SubmissionRequestWrapper<Form4Data>;
+    getHoldings(params: {
+        symbol: string;
+        lookback?: number;
+        fiscalYear?: number;
+        fiscalPeriod?: FiscalPeriod;
+        submissions?: SubmissionList;
+        documentXml?: string;
+    }): Promise<{
+        url: string | null;
+        holdingsForm: import("../../types").Form13FData | null;
+        submissions: FilingListItemTranslated[];
+    }>;
     /**
-     * Used for getting institutional holders. extracts holders urls from submission list response, and parses the xml doc.
+     * Gets institutional holders that have a large stake in the company.
+     * If multiple submissions are found within the fiscal period, uses the first submission.
+     *
+     * Forms: SC 13G, SC 13G/A
      *
-     * ```ts
-     * const submissions = await secEdgarApi.getSubmissions({ symbol: 'AAPL' })
-     * const requestWrapper = secEdgarApi.createRequestInstitutionalHolders({ symbol: 'AAPL', filings: submissions.filings.recent })
+     * Sends 2 requests by default, 1 request if submissions is provided, and 0 requests if documentXml is provided.
      *
-     * const holders1 = (await requestWrapper.requestNext()).result.holders // array of holders from most recent doc
-     * const holders2 = (await requestWrapper.requestNext()).result.holders // array of holders from second most recent doc
-     * ```
+     * WARNING: XML and HTML docs can be formatted differently and is prone to innacuracies.
      */
-    createRequestInstitutionalHolders(params: CreateRequestWrapperParams): SubmissionRequestWrapper<Form13GData>;
+    getInstitutionalHolders(params: {
+        symbol: string;
+        lookback?: number;
+        fiscalPeriod?: FiscalPeriod;
+        fiscalYear?: number;
+        submissions?: SubmissionList;
+        documentXml?: string;
+    }): Promise<{
+        url: string | null;
+        institutionalHolders: import("../../types").InstitutionalHolder[];
+        submissions: FilingListItemTranslated[];
+    }>;
     /**
-     * Used for getting earnings report tables from submission files.
+     * Gets executive compensation from the proxy statement.
      *
-     * ```ts
-     * const submissions = await secEdgarApi.getSubmissions({ symbol: 'AAPL' })
-     * const requestWrapper = secEdgarApi.createRequesEarningsReports({ symbol: 'AAPL', filings: submissions.filings.recent })
+     * Forms: DEF 14A
      *
-     * const tables1 = (await requestWrapper.requestNext()).result.tables // array of tables from most recent doc
-     * const tables2 = (await requestWrapper.requestNext()).result.tables // array of tables from second most recent doc
-     * ```
+     * Sends 2 requests by default, 1 request if submissions is provided, and 0 requests if documentXml is provided.
+     *
+     * WARNING: XML and HTML docs can be formatted differently and is prone to innacuracies.
      */
-    createRequestEarningsReports(params: CreateRequestWrapperParams): SubmissionRequestWrapper<Form10KData>;
+    getExecutivesCompensation(params: {
+        symbol: string;
+        lookback?: number;
+        fiscalYear?: number;
+        submissions?: SubmissionList;
+        documentXml?: string;
+    }): Promise<{
+        url: string | null;
+        executiveCompensation: import("../../types").ExecutiveCompensation[];
+        submissions: FilingListItemTranslated[];
+    }>;
     /**
-     * Proxy statement includes list of holders, executiveCompensation, and other tables. returns FormDef14aData
+     * Gets insider transactions - when a company's executives buy or sell shares, options, or other securities in the company.
+     *
+     * Forms: 4, 4/A, 5, 5/A
      *
-     * ```ts
-     * const submissions = await secEdgarApi.getSubmissions({ symbol: 'AAPL' })
-     * const requestWrapper = secEdgarApi.createRequesProxyStatement({ symbol: 'AAPL', filings: submissions.filings.recent })
+     * Sends 2 requests by default, 1 request if submissions is provided, and 0 requests if documentXml is provided.
      *
-     * const { holders, executiveCompensation } = (await requestWrapper.requestNext()).result
-     * ```
+     * WARNING: XML and HTML docs can be formatted differently and is prone to innacuracies.
+     */
+    getInsiderTransaction(params: {
+        symbol: string;
+        lookback: number;
+        submissions?: SubmissionList;
+        documentXml?: string;
+    }): Promise<{
+        url: string | null;
+        insiderTransaction: import("../../types").Form4Data | null;
+        submissions: FilingListItemTranslated[];
+    }>;
+    /**
+     * @see https://www.sec.gov/structureddata/rss-feeds-submitted-filings
      */
-    createRequestProxyStatement(params: CreateRequestWrapperParams): SubmissionRequestWrapper<FormDef14aData>;
+    getCurrentFilings(params?: {
+        taxonomy?: 'usGaap' | 'mutualFund' | 'inlineXbrl' | 'allXbrl';
+    }): Promise<import("../../types/current-filings.type").CurrentFilingsList | null>;
 }
 export {};