edgar-ts

TypeScript SEC EDGAR client for filing discovery, company data, XBRL financials, and full-text search.

Installation

npm install edgar-ts
# or
pnpm add edgar-ts
# or
yarn add edgar-ts

Requirements

• Node.js 20.0.0+ or Bun 1.0+
• Zero runtime dependencies

Features

• Filing discovery — Date-bounded search with optional CIK and form-type filtering
• Index file discovery — Bulk discovery across all filers via SEC quarterly index files
• Company metadata — Name, tickers, SIC code, entity type, state of incorporation
• Ticker/name lookup — Resolve tickers or company names to CIKs
• Exhibit enumeration — Normalized exhibit metadata from filing indices
• Contract filtering — Built-in EX-10* contract exhibit isolation
• Raw download — Exhibit bytes with MIME hints and SHA-256 integrity hash
• Bulk data — Download SEC nightly archives (submissions.zip, companyfacts.zip)
• XBRL financials — Company Facts, Company Concept, and Frames API access
• Full-text search — Keyword search across all SEC filings via EFTS
• SEC-compliant — Mandatory user-agent, rate limiting (8 req/s default), bounded retries
• Deterministic — Canonical normalization, stable sort, deduplication
• Zero dependencies — No runtime dependencies
• Dual runtime — Node.js and Bun support

Quick Start

import { EdgarClient } from "edgar-ts"

const client = new EdgarClient({
  userAgent: "AcmeLegalBot/1.0 ([email protected])",
})

// Look up a company by ticker
const matches = await client.lookupCompany("AAPL")
const { cik } = matches[0] // "0000320193"

// Get company metadata
const company = await client.getCompanyInfo(cik)
console.log(company.name, company.sic, company.tickers)

// Discover filings for a specific company
const filings = await client.discoverFilings({
  cik,
  from: "2026-01-01",
  to: "2026-12-31",
})

// Or discover across ALL filers (uses quarterly index files)
const allFilings = await client.discoverFilings({
  from: "2026-01-01",
  to: "2026-03-31",
  formTypes: ["10-K"],
})

// Get contract exhibits (EX-10*) for a filing
for (const filing of filings) {
  const exhibits = await client.listContractExhibits(filing)
  for (const exhibit of exhibits) {
    const { bytes, sha256, sizeBytes } = await client.downloadExhibit(exhibit)
    // Store bytes and metadata in your downstream system
  }
}

API

new EdgarClient(options)

| Option | Type | Default | Description | |--------|------|---------|-------------| | userAgent | string | required | Descriptive user-agent for SEC compliance | | maxRequestsPerSecond | number | 8 | Global request rate cap | | timeoutMs | number | 10000 | Per-request timeout | | retries | RetryOptions | { maxAttempts: 3, baseDelayMs: 250, maxDelayMs: 4000 } | Retry configuration | | telemetry | TelemetryOptions | — | Optional request/retry hooks |

Methods

Company Data

| Method | Returns | Description | |--------|---------|-------------| | getCompanyInfo(cik) | Promise<CompanyInfo> | Company metadata (name, tickers, SIC, entity type, etc.) | | lookupCompany(query) | Promise<CompanyTicker[]> | Search by ticker (exact) or company name (substring) |

Filing Discovery

| Method | Returns | Description | |--------|---------|-------------| | discoverFilings(input) | Promise<FilingRef[]> | Date-bounded filing discovery. With CIK: uses Submissions API. Without CIK: uses quarterly index files. |

Exhibits

| Method | Returns | Description | |--------|---------|-------------| | listExhibits(filing) | Promise<ExhibitRef[]> | All exhibits for a filing | | listContractExhibits(filing) | Promise<ExhibitRef[]> | Contract exhibits only (EX-10*) | | downloadExhibit(exhibit) | Promise<DownloadedExhibit> | Raw bytes + metadata + SHA-256 |

Bulk Data

| Method | Returns | Description | |--------|---------|-------------| | downloadSubmissionsBulk() | Promise<BulkDownloadResult> | Download SEC nightly submissions.zip (~2GB) | | downloadCompanyFactsBulk() | Promise<BulkDownloadResult> | Download SEC nightly companyfacts.zip |

XBRL Financials

| Method | Returns | Description | |--------|---------|-------------| | getCompanyFacts(cik) | Promise<CompanyFacts> | All XBRL facts across all filings | | getCompanyConcept(cik, taxonomy, tag) | Promise<CompanyConcept> | Single concept time series (e.g., us-gaap/Revenue) | | getFrame(taxonomy, tag, unit, period) | Promise<Frame> | Cross-company comparison at a point in time |

Full-Text Search

| Method | Returns | Description | |--------|---------|-------------| | searchFilings(query) | Promise<SearchResult> | Keyword search with form type, date, and entity filters |

Note: searchFilings wraps the SEC's EFTS Elasticsearch API, which is undocumented and could change without notice.

Examples

Company lookup and metadata

// Find a company by ticker
const results = await client.lookupCompany("MSFT")
// [{ cik: "0000789019", ticker: "MSFT", name: "MICROSOFT CORP", exchange: "Nasdaq" }]

// Get full company metadata
const info = await client.getCompanyInfo("789019")
// { cik: "0000789019", name: "MICROSOFT CORP", tickers: ["MSFT"], sic: "7372", ... }

Filing discovery

// Discover filings for a specific company
const filings = await client.discoverFilings({
  cik: "320193",
  from: "2026-01-01",
  to: "2026-12-31",
})

// Discover across all filers (no CIK — uses index files)
const allFilings = await client.discoverFilings({
  from: "2026-01-01",
  to: "2026-03-31",
  formTypes: ["10-K", "10-Q"],
})

// Custom form types for a specific company
const proxyFilings = await client.discoverFilings({
  cik: "320193",
  from: "2026-01-01",
  to: "2026-12-31",
  formTypes: ["DEF 14A"],
})

XBRL financial data

// Get all XBRL facts for Apple
const facts = await client.getCompanyFacts("320193")

// Get Revenue time series
const revenue = await client.getCompanyConcept("320193", "us-gaap", "Revenue")
for (const val of revenue.units.USD) {
  console.log(`FY${val.fy}: $${val.val}`)
}

// Compare Revenue across all companies for Q1 2024
const frame = await client.getFrame("us-gaap", "Revenue", "USD", "CY2024Q1")
console.log(`${frame.data.length} companies reported Revenue`)

Full-text search

// Search for filings mentioning "non-compete"
const results = await client.searchFilings({
  q: "non-compete agreement",
  formTypes: ["10-K", "8-K"],
  from: "2024-01-01",
  to: "2024-12-31",
})

console.log(`${results.total} filings found`)
for (const hit of results.hits) {
  console.log(`${hit.entityName} — ${hit.formType} (${hit.fileDate})`)
}

Exhibits and downloads

const filing = filings[0]
const exhibits = await client.listExhibits(filing)
const contracts = await client.listContractExhibits(filing)

const downloaded = await client.downloadExhibit(contracts[0])
console.log(`Downloaded ${downloaded.sizeBytes} bytes`)
console.log(`SHA-256: ${downloaded.sha256}`)
console.log(`MIME type: ${downloaded.mimeType || "unknown"}`)

Type Exports

import type {
  EdgarClientOptions,
  FilingRef,
  ExhibitRef,
  DownloadedExhibit,
  CompanyInfo,
  CompanyTicker,
} from "edgar-ts"

Error Handling

import { EdgarError, ValidationError, TimeoutError } from "edgar-ts"

try {
  await client.discoverFilings(input)
} catch (err) {
  if (err instanceof ValidationError) {
    // Invalid input parameters
  } else if (err instanceof TimeoutError) {
    // Request exceeded timeout
  }
}

Telemetry & Observability

edgar-ts provides optional telemetry helpers for logging and metrics:

Console Logger

Human-readable colored output for development:

import { EdgarClient } from "edgar-ts"
import { createConsoleLogger } from "edgar-ts/telemetry"

const client = new EdgarClient({
  userAgent: "MyBot/1.0 ([email protected])",
  telemetry: createConsoleLogger()
})

// Outputs:
// → GET https://data.sec.gov/submissions/... [discoverFilings] {abc12345}
// ← 200 GET https://data.sec.gov/submissions/... 1234ms [discoverFilings]
// ⟳ Retry 2/3 after 500ms: GET ... (TIMEOUT)

Metrics Aggregator

Track request lifecycle and rate limiting metrics:

import { createMetricsAggregator } from "edgar-ts/telemetry"

const metrics = createMetricsAggregator()
const client = new EdgarClient({
  userAgent: "MyBot/1.0 ([email protected])",
  telemetry: metrics
})

// ... make requests ...

const snapshot = metrics.getSnapshot()
console.log(snapshot.requestsTotal)       // 42
console.log(snapshot.requestsSuccessful)  // 40
console.log(snapshot.requestsFailed)      // 2
console.log(snapshot.latencyByOperation)  // { discoverFilings: { avg: 250, min: 100, max: 1200 } }
console.log(snapshot.rateLimitedRequests)  // 0

Structured Logger

JSON Lines output for log aggregation systems:

import { createStructuredLogger } from "edgar-ts/telemetry"

const client = new EdgarClient({
  userAgent: "MyBot/1.0 ([email protected])",
  telemetry: createStructuredLogger()
})

// Outputs JSON Lines:
// {"event":"request.start","url":"...","operation":"discoverFilings",...}
// {"event":"request.end","statusCode":200,"durationMs":1234,...}
// {"event":"request.retry","attempt":2,"error":"TIMEOUT",...}

Custom Telemetry

Implement your own hooks for integration with observability platforms:

const client = new EdgarClient({
  userAgent: "MyBot/1.0 ([email protected])",
  telemetry: {
    onRequestStart: (event) => {
      console.log(`Starting ${event.operation} (${event.requestId})`)
    },
    onRequestEnd: (event) => {
      console.log(`Completed in ${event.durationMs}ms`)
    },
    onRetry: (event) => {
      console.log(`Retry ${event.attempt}/${event.maxAttempts}`)
    }
  }
})

Telemetry Event Fields:

• requestId - Unique ID for request correlation
• operation - EdgarClient method (discoverFilings, listExhibits, getCompanyInfo, searchFilings, etc.)
• endpointClass - SEC endpoint type (submissions, archive, full-index, xbrl, efts, files, bulk-data)
• runtime - Detected runtime (node or bun)
• timestamp - Event timestamp (milliseconds)
• url, method, statusCode, durationMs - Request details

Development

pnpm install        # Install dependencies
pnpm test:run       # Run tests
pnpm build          # Build (ESM + CJS)
pnpm lint           # Lint
pnpm typecheck      # Type check

License

MIT