sec-edgar-toolkit
Version:
Open source toolkit to facilitate working with the SEC EDGAR database
441 lines • 12.5 kB
TypeScript
/**
* SEC EDGAR API client with fluent interface design - TypeScript implementation
*
* This module provides a comprehensive toolkit for accessing and analyzing
* SEC filing data through a chainable API interface.
*/
import { EdgarClient as BaseEdgarClient } from './client/edgar-client';
import { CompanyTicker, EdgarClientConfig } from './types';
/**
* Query options for filing searches
*/
export interface FilingQueryOptions {
formTypes?: string[];
since?: string;
until?: string;
limit?: number;
}
/**
* Options for XBRL fact queries
*/
export interface FactQueryOptions {
concept?: string;
taxonomy?: string;
units?: string;
period?: string;
}
/**
* Financial summary data
*/
export interface FinancialSummary {
totalAssets?: number;
totalLiabilities?: number;
totalStockholdersEquity?: number;
totalRevenues?: number;
}
/**
* Key financial ratios
*/
export interface FinancialRatios {
debtToAssets?: number;
debtToEquity?: number;
currentRatio?: number;
quickRatio?: number;
returnOnEquity?: number;
returnOnAssets?: number;
netProfitMargin?: number;
grossProfitMargin?: number;
operatingCashFlowMargin?: number;
}
/**
* SEC EDGAR API client with fluent interface design.
*
* This client provides comprehensive access to SEC filing data through
* a chainable, type-safe API with intelligent caching and rate limiting.
*
* @example
* ```typescript
* const client = new EdgarClient({ userAgent: "MyApp/1.0 (contact@example.com)" });
* const company = await client.companies.lookup("AAPL");
* const filings = await company?.filings.formTypes(["10-K"]).limit(5).fetch();
* ```
*/
export declare class EdgarClient {
private baseClient;
readonly companies: CompanyQueryBuilder;
readonly filings: FilingQueryBuilder;
readonly facts: FactsQueryBuilder;
constructor(config: EdgarClientConfig);
/**
* Configure client settings with method chaining.
*/
configure(_settings: Partial<EdgarClientConfig>): EdgarClient;
}
/**
* Fluent interface for company queries.
*/
export declare class CompanyQueryBuilder {
private client;
constructor(client: BaseEdgarClient);
/**
* Look up a single company by ticker or CIK.
*
* @param identifier - Ticker symbol or CIK number
* @returns Company object if found
*
* @example
* ```typescript
* const company = await client.companies.lookup("AAPL");
* ```
*/
lookup(identifier: string | number): Promise<Company | null>;
/**
* Search for companies with fluent interface.
*
* @param query - Search query
* @returns CompanySearchBuilder for further filtering
*
* @example
* ```typescript
* const results = await client.companies.search("Apple").limit(5).execute();
* ```
*/
search(query: string): CompanySearchBuilder;
/**
* Look up multiple companies in batch.
*
* @param identifiers - List of ticker symbols or CIKs
* @returns Array of Company objects (null for not found)
*
* @example
* ```typescript
* const companies = await client.companies.batchLookup(["AAPL", "MSFT", "GOOGL"]);
* ```
*/
batchLookup(identifiers: Array<string | number>): Promise<Array<Company | null>>;
}
/**
* Builder for company search queries.
*/
export declare class CompanySearchBuilder {
private client;
private query;
private _limit?;
constructor(client: BaseEdgarClient, query: string);
/**
* Limit number of results.
*/
limit(count: number): CompanySearchBuilder;
/**
* Execute the search query.
*/
execute(): Promise<Company[]>;
}
/**
* Fluent interface for filing queries.
*/
export declare class FilingQueryBuilder {
private client;
constructor(client: BaseEdgarClient);
/**
* Get filings for a specific company.
*
* @param company - Company object, ticker, or CIK
* @returns CompanyFilingBuilder for further filtering
*
* @example
* ```typescript
* const filings = await client.filings.forCompany("AAPL").formTypes(["10-K"]).recent(5).fetch();
* ```
*/
forCompany(company: Company | string | number): CompanyFilingBuilder;
}
/**
* Builder for company filing queries.
*/
export declare class CompanyFilingBuilder {
private client;
private companyIdentifier;
private _formTypes?;
private _since?;
private _until?;
private _limit?;
constructor(client: BaseEdgarClient, companyIdentifier: string | number);
/**
* Filter by form types.
*/
formTypes(forms: string[]): CompanyFilingBuilder;
/**
* Filter filings since date (YYYY-MM-DD).
*/
since(date: string): CompanyFilingBuilder;
/**
* Filter filings until date (YYYY-MM-DD).
*/
until(date: string): CompanyFilingBuilder;
/**
* Limit to most recent filings.
*/
recent(count: number): CompanyFilingBuilder;
/**
* Execute the query and fetch filings.
*/
fetch(): Promise<Filing[]>;
}
/**
* Fluent interface for XBRL facts queries.
*/
export declare class FactsQueryBuilder {
private client;
constructor(client: BaseEdgarClient);
/**
* Get facts for a specific company.
*
* @param company - Company object, ticker, or CIK
* @returns CompanyFactsBuilder for further querying
*
* @example
* ```typescript
* const facts = await client.facts.forCompany("AAPL").concept("Assets").inUnits("USD").fetch();
* ```
*/
forCompany(company: Company | string | number): CompanyFactsBuilder;
}
/**
* Builder for company facts queries.
*/
export declare class CompanyFactsBuilder {
private client;
private companyIdentifier;
private _concept?;
private _taxonomy;
private _units?;
private _period?;
constructor(client: BaseEdgarClient, companyIdentifier: string | number);
/**
* Filter by specific concept.
*/
concept(conceptName: string): CompanyFactsBuilder;
/**
* Specify taxonomy (default: us-gaap).
*/
taxonomy(taxonomyName: string): CompanyFactsBuilder;
/**
* Filter by units (e.g., USD, shares).
*/
inUnits(units: string): CompanyFactsBuilder;
/**
* Filter by period.
*/
period(periodFilter: string): CompanyFactsBuilder;
/**
* Execute the query and fetch facts.
*/
fetch(): Promise<Array<Record<string, any>>>;
private processConceptData;
private processAllFacts;
}
/**
* Comprehensive company representation with fluent interface design.
*
* This class provides rich access to company data, filings, and financial
* information through an intuitive, chainable API.
*/
export declare class Company {
private data;
private client;
readonly cik: string;
readonly ticker: string;
readonly name: string;
readonly exchange: string;
constructor(data: CompanyTicker, client: BaseEdgarClient);
/**
* Get filings builder for this company.
*/
get filings(): CompanyFilingBuilder;
/**
* Get facts builder for this company.
*/
get facts(): CompanyFactsBuilder;
/**
* Get the most recent filing of a specific type.
*
* @param formType - Type of form to retrieve
* @returns Most recent filing or null
*
* @example
* ```typescript
* const latest10K = await company.getLatestFiling("10-K");
* ```
*/
getLatestFiling(formType?: string): Promise<Filing | null>;
/**
* Get a summary of key financial metrics.
*
* @returns Object with key financial data
*
* @example
* ```typescript
* const summary = await company.getFinancialSummary();
* console.log(`Assets: $${summary.totalAssets?.toLocaleString()}`);
* ```
*/
getFinancialSummary(): Promise<FinancialSummary>;
toString(): string;
}
/**
* Comprehensive filing representation with advanced content processing.
*
* This class provides rich access to SEC filing content, structured data
* extraction, and financial analysis capabilities.
*/
export declare class Filing {
private data;
private client;
readonly cik: string;
readonly accessionNumber: string;
readonly formType: string;
readonly filingDate: string;
private extractedItems;
private itemExtractor;
constructor(data: Record<string, any>, client: BaseEdgarClient);
/**
* Get content access interface.
*/
get content(): FilingContentAccess;
/**
* Get analysis interface.
*/
get analysis(): FilingAnalysis;
/**
* Get XBRL instance for this filing.
*
* @returns XBRLInstance for accessing XBRL data
*
* @example
* ```typescript
* const xbrl = await filing.xbrl();
* const assets = await xbrl.getConceptValue("Assets");
* ```
*/
xbrl(): Promise<any>;
/**
* Get API access for internal use
*/
get api(): any;
/**
* Get a preview of the filing content.
*
* @param length - Number of characters to preview
* @returns Preview text
*/
preview(length?: number): Promise<string>;
/**
* Extract individual items from the filing (e.g., Item 1, Item 1A, etc.).
*
* @param itemNumbers - Optional list of specific item numbers to extract.
* If not provided, extracts all items.
* @returns Dictionary mapping item numbers to their content
*
* @example
* const filing = await company.getFiling("10-K");
* const items = await filing.extractItems();
* console.log(items["1"]); // Business section
* console.log(items["1A"]); // Risk Factors
*
* // Extract specific items only
* const specificItems = await filing.extractItems(["1", "1A", "7"]);
*/
extractItems(itemNumbers?: string[]): Promise<Record<string, string>>;
/**
* Get a specific item from the filing.
*
* @param itemNumber - The item number to retrieve (e.g., "1", "1A", "7")
* @returns The item content or undefined if not found
*
* @example
* const filing = await company.getFiling("10-K");
* const riskFactors = await filing.getItem("1A");
* const business = await filing.getItem("1");
*/
getItem(itemNumber: string): Promise<string | undefined>;
/**
* Get all extracted items from the filing.
*
* This is a convenience property that extracts all items.
*
* @returns Dictionary mapping item numbers to their content
*
* @example
* const filing = await company.getFiling("10-K");
* const allItems = await filing.items;
* for (const [itemNum, content] of Object.entries(allItems)) {
* console.log(`Item ${itemNum}: ${content.length} characters`);
* }
*/
get items(): Promise<Record<string, string>>;
toString(): string;
}
/**
* Interface for accessing filing content.
*/
export declare class FilingContentAccess {
private filing;
constructor(filing: Filing);
/**
* Get filing as plain text.
*/
asText(clean?: boolean): Promise<string>;
/**
* Get filing as HTML.
*/
asHtml(): Promise<string>;
/**
* Get filing as structured data.
*/
asStructuredData(): Promise<Record<string, any>>;
/**
* Get direct download URL.
*/
getDownloadUrl(): string;
}
/**
* Interface for filing analysis and extraction.
*/
export declare class FilingAnalysis {
private filing;
constructor(filing: Filing);
/**
* Extract financial data if available.
*/
extractFinancials(): Promise<FinancialData | null>;
/**
* Extract key business metrics.
*/
extractKeyMetrics(): Promise<Record<string, any>>;
}
/**
* Enhanced financial data interface.
*/
export declare class FinancialData {
private filing;
constructor(filing: Filing);
/**
* Get balance sheet data.
*/
getBalanceSheet(): Promise<Record<string, any> | null>;
/**
* Get income statement data.
*/
getIncomeStatement(): Promise<Record<string, any> | null>;
/**
* Get cash flow statement data.
*/
getCashFlow(): Promise<Record<string, any> | null>;
/**
* Calculate key financial ratios.
*/
getKeyRatios(): Promise<FinancialRatios>;
}
export declare function createClient(config: EdgarClientConfig): EdgarClient;
//# sourceMappingURL=edgar.d.ts.map