@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 admin@myapp.com',
});

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 admin@myapp.com',
});

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.