Package Exports

@omnifolio/sec-toolkit
@omnifolio/sec-toolkit/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@omnifolio/sec-toolkit) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@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.