@omnifolio/sec-toolkit

Production-grade SEC EDGAR toolkit for parsing XBRL financial data, extracting filing text, and analyzing SEC filings. Supports 10-K, 10-Q, 8-K, 20-F, and 6-K forms with both US-GAAP and IFRS tag mappings.

Built and maintained by the team at Omnifolio — a financial intelligence platform for portfolios, SEC filings, and economic data.

Features

• 🏦 XBRL Parser — Extract structured income statements, balance sheets, and cash flows from SEC company facts
• 📄 Text Extractor — Parse 10-K/10-Q/8-K/20-F filings into named sections (Risk Factors, MD&A, etc.)
• 📊 Financial Metrics — Auto-calculate margins, ratios, ROE, ROA, current ratio, debt-to-equity, and more
• 🔍 Sentiment Analysis — Built-in word-list sentiment scoring (no ML dependencies)
• 🔎 Keyword Extraction — Categorize terms as risk, growth, financial, or legal
• 📈 Filing Comparison — Jaccard similarity diff between filings, detect new/removed risk factors
• 🌍 IFRS Support — Full tag mappings for foreign private issuers (20-F / 6-K)
• 🔒 Rate Limiting — Built-in SEC Fair Access Policy compliance (configurable req/s)
• 💵 Formatters — $1.23B, +25.50%, full currency formatting
• 🔌 Injectable Client — BYO HTTP client or use the built-in one

Installation

npm install @omnifolio/sec-toolkit

Quick Start

Parse Financial Statements

import { XBRLParser, createSECClient } from '@omnifolio/sec-toolkit';

// SEC requires a User-Agent with contact info
const client = createSECClient({
  userAgent: 'MyApp [email protected]',
});

const parser = new XBRLParser(client);

// Parse Apple's financials
const statements = await parser.parseFilingFinancials({
  cik: '0000320193',
  form: '10-K',
  companyName: 'Apple Inc.',
  accessionNumber: '0000320193-23-000106',
  filingDate: '2023-11-03',
  primaryDocument: 'aapl-20230930.htm',
  primaryDocumentUrl: 'https://www.sec.gov/Archives/edgar/data/320193/...',
  filingDetailUrl: 'https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000320193',
  size: 0,
});

// Access structured data
const latest = statements[0];
console.log('Revenue:', latest.incomeStatement.revenue);
console.log('Net Income:', latest.incomeStatement.netIncome);
console.log('Gross Margin:', latest.metrics.grossMargin?.toFixed(1) + '%');
console.log('Current Ratio:', latest.metrics.currentRatio?.toFixed(2));
console.log('Debt/Equity:', latest.metrics.debtToEquity?.toFixed(2));

Extract Filing Text & Analyze

import { SECTextExtractor } from '@omnifolio/sec-toolkit';

const extractor = new SECTextExtractor({
  userAgent: 'MyApp [email protected]',
});

const sections = await extractor.extractAllSections(filing);

for (const section of sections) {
  console.log(`📄 ${section.title}`);
  console.log(`   Words: ${section.wordCount}`);
  console.log(`   Sentiment: ${section.sentiment?.label} (${section.sentiment?.score.toFixed(2)})`);
  console.log(`   Top keywords:`, section.keywords.slice(0, 5).map(k => k.word).join(', '));
}

Compare Filings Year-over-Year

const comparison = await extractor.compareFilings(currentFiling, previousFiling);

console.log(`Overall similarity: ${(comparison.overallSimilarity * 100).toFixed(1)}%`);
console.log(`New risks: ${comparison.newRisks.length}`);
console.log(`Removed risks: ${comparison.removedRisks.length}`);

for (const risk of comparison.newRisks) {
  console.log(`  🆕 ${risk}`);
}

Format Financial Numbers

import { formatCurrency, formatLargeNumber, formatPercentage } from '@omnifolio/sec-toolkit';

formatCurrency(1234567);         // "$1,234,567"
formatLargeNumber(394328000000); // "$394.33B"
formatLargeNumber(-2500000);     // "-$2.50M"
formatPercentage(25.5);          // "+25.50%"
formatPercentage(-3.2);          // "-3.20%"

Get Metric History

const revenueHistory = await parser.getMetricHistory(
  '0000320193', // Apple CIK
  'Revenues',
  10 // last 10 periods
);

for (const point of revenueHistory) {
  console.log(`${point.period}: ${formatLargeNumber(point.value)}`);
}

Bring Your Own Client

import { XBRLParser } from '@omnifolio/sec-toolkit';
import type { SECClient } from '@omnifolio/sec-toolkit';

// Implement the minimal SECClient interface
const myClient: SECClient = {
  async getCompanyFacts(cik: string) {
    const res = await myCustomFetch(`https://data.sec.gov/api/xbrl/companyfacts/CIK${cik}.json`);
    return res.json();
  },
};

const parser = new XBRLParser(myClient);

API Reference

Classes

| Class | Description | |-------|-------------| | XBRLParser | Parses XBRL financial data from SEC company facts API | | SECTextExtractor | Extracts and analyzes text from SEC filing HTML documents |

Factory Functions

| Function | Description | |----------|-------------| | createSECClient(options) | Creates a built-in SEC EDGAR client with rate limiting |

Formatters

| Function | Description | |----------|-------------| | formatCurrency(value, options?) | Format as USD currency ($1,234,567) | | formatLargeNumber(value) | Abbreviated format ($1.23B) | | formatPercentage(value, decimals?) | Signed percentage (+25.50%) |

Exported Constants

| Export | Description | |--------|-------------| | TAG_MAPS | All US-GAAP and IFRS tag → field mappings | | KEYWORD_SETS | Risk, growth, financial, legal, positive, negative word sets |

Key Types

| Type | Description | |------|-------------| | SECFiling | Filing metadata (CIK, form type, dates, URLs) | | ParsedFinancialStatement | Full parsed financial data with metrics | | IncomeStatementData | Revenue, expenses, net income, EPS | | BalanceSheetData | Assets, liabilities, equity breakdown | | CashFlowData | Operating, investing, financing cash flows | | CalculatedMetrics | Derived ratios (margins, liquidity, leverage) | | ExtractedSection | Parsed filing section with text analysis | | FilingComparison | Filing-to-filing diff result |

Supported Form Types

| Form | Description | Parser | Text Extractor | |------|-------------|--------|---------------| | 10-K | Annual report (US domestic) | ✅ | ✅ | | 10-Q | Quarterly report | ✅ | ✅ | | 8-K | Current report | — | ✅ | | 20-F | Annual report (foreign private issuer) | ✅ | ✅ | | 6-K | Semi-annual/quarterly (foreign) | ✅ | — |

XBRL Tag Coverage

The parser maps 100+ US-GAAP tags and 30+ IFRS tags across:

• Income statement (revenue, expenses, EPS, shares)
• Balance sheet (assets, liabilities, equity)
• Cash flow (operating, investing, financing)

See TAG_MAPS for the complete mapping.

SEC Fair Access Policy

This toolkit respects SEC's Fair Access Policy:

• Built-in rate limiting (default: 4 req/s, configurable)
• Requires User-Agent header with contact information
• No authentication required — SEC EDGAR is public domain data

License

MIT — see LICENSE for details.

About Omnifolio

This package is extracted from Omnifolio, a financial intelligence platform that tracks portfolios, SEC filings, Congressional trading, and economic indicators.

We open-source the tools we build. If you find this useful, check out omnifolio.app.