@rdcahalane/edgar-client 0.1.0

package/README.md

@@ -0,0 +1,35 @@
+# @rdcahalane/edgar-client
+
+Unified client for public SEC EDGAR data.
+
+## Features
+
+- ticker-to-CIK lookup
+- full-text filing search
+- XBRL financial series access
+- Form 4 insider transaction parsing
+- 8-K event parsing
+
+## Install
+
+```bash
+npm install @rdcahalane/edgar-client
+```
+
+## Usage
+
+```ts
+import { lookupCIK, searchFilings, fetchFinancials } from "@rdcahalane/edgar-client";
+
+const cik = await lookupCIK("AAPL");
+const filings = await searchFilings({ ticker: "AAPL", form: "8-K" });
+const revenue = await fetchFinancials("AAPL", "RevenueFromContractWithCustomerExcludingAssessedTax");
+```
+
+## Notes
+
+- No API key required
+- Includes courtesy delays for SEC-friendly usage
+- You should set a real contact address in the User-Agent before production use
+
+Good for finance tools, public-company research, and filing ingestion pipelines.

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@rdcahalane/edgar-client",
+  "version": "0.1.0",
+  "description": "Unified SEC EDGAR client: CIK lookup, EFTS search, XBRL financials, Form 4, 8-K parsing. Zero API key needed.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit --pretty false"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5"
+  }
+}

package/src/cik.ts

@@ -0,0 +1,59 @@
+/**
+ * CIK (Central Index Key) resolution.
+ *
+ * Maps ticker symbols to SEC CIK numbers and vice versa.
+ * Uses company_tickers.json — loaded once and cached.
+ */
+
+import { edgarFetch, RATE_LIMIT_MS } from "./index.js";
+
+export interface CIKEntry {
+  cik: number;
+  ticker: string;
+  name: string;
+}
+
+let _tickerMap: Map<string, CIKEntry> | null = null;
+let _cikMap: Map<number, CIKEntry> | null = null;
+
+/**
+ * Load the full SEC ticker→CIK mapping. Cached after first call.
+ */
+export async function loadTickerMap(): Promise<Map<string, CIKEntry>> {
+  if (_tickerMap) return _tickerMap;
+
+  const r = await edgarFetch("https://www.sec.gov/files/company_tickers.json");
+  if (!r.ok) throw new Error(`Failed to load company_tickers.json: ${r.status}`);
+  const data = await r.json() as Record<string, { cik_str: number; ticker: string; title: string }>;
+
+  _tickerMap = new Map();
+  _cikMap = new Map();
+
+  for (const entry of Object.values(data)) {
+    const e: CIKEntry = {
+      cik: entry.cik_str,
+      ticker: entry.ticker.toUpperCase(),
+      name: entry.title,
+    };
+    _tickerMap.set(e.ticker, e);
+    _cikMap.set(e.cik, e);
+  }
+
+  return _tickerMap;
+}
+
+/**
+ * Resolve ticker → CIK number. Returns null if not found.
+ */
+export async function lookupCIK(ticker: string): Promise<number | null> {
+  const map = await loadTickerMap();
+  return map.get(ticker.toUpperCase())?.cik ?? null;
+}
+
+/**
+ * Resolve CIK → ticker symbol. Returns null if not found.
+ */
+export async function lookupTicker(cik: number): Promise<string | null> {
+  if (!_cikMap) await loadTickerMap();
+  return _cikMap!.get(cik)?.ticker ?? null;
+}

package/src/efts.ts

@@ -0,0 +1,98 @@
+/**
+ * EDGAR Full-Text Search (EFTS)
+ *
+ * Search SEC filings by form type, date range, and content keywords.
+ * Used by 8-K, Form 4, 10-K, DEF 14A scrapers.
+ */
+
+import { edgarFetch, RATE_LIMIT_MS } from "./index.js";
+
+export interface FilingSearchResult {
+  accessionNo: string;
+  cik: number;
+  ticker?: string;
+  companyName: string;
+  formType: string;
+  filedAt: string;
+  documentUrl: string;
+  description?: string;
+}
+
+const EFTS_BASE = "https://efts.sec.gov/LATEST/search-index";
+
+interface EFTSParams {
+  /** Free-text query (e.g. '"Item 5.02"') */
+  query?: string;
+  /** Form types to search (e.g. "8-K", "10-K", "DEF 14A") */
+  forms?: string;
+  /** Start date (YYYY-MM-DD) */
+  startDate?: string;
+  /** End date (YYYY-MM-DD) */
+  endDate?: string;
+  /** Max results per page */
+  count?: number;
+  /** Start index for pagination */
+  from?: number;
+}
+
+/**
+ * Search EDGAR filings via the full-text search API.
+ *
+ * @example
+ * // Find 8-K filings mentioning executive transitions in the last 90 days
+ * const results = await searchFilings({
+ *   query: '"Item 5.02"',
+ *   forms: '8-K',
+ *   startDate: '2025-01-01',
+ * });
+ */
+export async function searchFilings(params: EFTSParams): Promise<FilingSearchResult[]> {
+  const searchParams = new URLSearchParams();
+
+  if (params.query) searchParams.set("q", params.query);
+  if (params.forms) searchParams.set("forms", params.forms);
+  if (params.startDate || params.endDate) {
+    searchParams.set("dateRange", "custom");
+    if (params.startDate) searchParams.set("startdt", params.startDate);
+    if (params.endDate) searchParams.set("enddt", params.endDate);
+  }
+  searchParams.set("from", String(params.from ?? 0));
+  searchParams.set("count", String(params.count ?? 40));
+
+  const url = `${EFTS_BASE}?${searchParams}`;
+  const r = await edgarFetch(url);
+  if (!r.ok) return [];
+
+  const data = await r.json() as {
+    hits: {
+      hits: Array<{
+        _source: Record<string, unknown> & {
+          display_names?: string[];
+        };
+      }>;
+    };
+  };
+
+  const hits = data?.hits?.hits ?? [];
+  const results: FilingSearchResult[] = [];
+
+  for (const hit of hits) {
+    const src = hit._source;
+    const accNo = String(src.file_num ?? src.accession_no ?? "").replace(/-/g, "");
+    const cik = Number(src.entity_id ?? src.cik ?? 0);
+
+    results.push({
+      accessionNo: accNo,
+      cik,
+      companyName: String(src.entity_name ?? src.display_names?.[0] ?? ""),
+      formType: String(src.form_type ?? src.file_type ?? ""),
+      filedAt: String(src.file_date ?? src.filed_at ?? ""),
+      documentUrl: src.file_url
+        ? String(src.file_url)
+        : `https://www.sec.gov/Archives/edgar/data/${cik}/${accNo}/`,
+      description: String(src.display_description ?? ""),
+    });
+  }
+
+  return results;
+}

package/src/filing8k.ts

@@ -0,0 +1,140 @@
+/**
+ * 8-K Filing Parser
+ *
+ * Extracts structured events from SEC 8-K filings:
+ *   - Item 5.02: Executive transitions (appointments/departures)
+ *   - Item 2.04: Debt triggers
+ *   - Item 1.01: M&A/material agreements
+ *   - Item 1.02: Contract terminations
+ *   - Item 2.05: Workforce reductions
+ *   - Item 4.02: Financial restatements
+ *   - Item 1.05: Cybersecurity incidents
+ */
+
+import { searchFilings } from "./efts.js";
+import { edgarFetch, RATE_LIMIT_MS } from "./index.js";
+
+export interface Event8K {
+  ticker?: string;
+  companyName: string;
+  cik: number;
+  item: string;
+  itemDescription: string;
+  eventDate?: string;
+  filingDate: string;
+  accessionNo: string;
+  documentUrl: string;
+  /** Extracted people (for Item 5.02) */
+  people?: Array<{
+    name: string;
+    role_raw?: string;
+    direction: "appointment" | "departure" | "unknown";
+  }>;
+  /** Raw text snippet from the filing */
+  excerpt?: string;
+}
+
+const ITEM_DESCRIPTIONS: Record<string, string> = {
+  "1.01": "Entry into Material Agreement",
+  "1.02": "Termination of Material Agreement",
+  "1.05": "Material Cybersecurity Incident",
+  "2.04": "Triggering Events (Debt Acceleration)",
+  "2.05": "Costs of Workforce Reduction",
+  "4.02": "Non-Reliance on Previously Issued Financial Statements",
+  "5.02": "Departure/Election of Directors or Officers",
+};
+
+/**
+ * Fetch 8-K events for a specific item type.
+ *
+ * @example
+ * // Get executive transitions from the last 90 days
+ * const events = await fetch8KEvents("5.02", { daysBack: 90 });
+ */
+export async function fetch8KEvents(
+  item: string,
+  opts: { daysBack?: number; limit?: number } = {}
+): Promise<Event8K[]> {
+  const daysBack = opts.daysBack ?? 90;
+  const limit = opts.limit ?? 100;
+
+  const endDate = new Date();
+  const startDate = new Date(endDate.getTime() - daysBack * 86400000);
+
+  const filings = await searchFilings({
+    query: `"Item ${item}"`,
+    forms: "8-K",
+    startDate: startDate.toISOString().slice(0, 10),
+    endDate: endDate.toISOString().slice(0, 10),
+    count: Math.min(limit, 40),
+  });
+
+  const events: Event8K[] = [];
+
+  for (const filing of filings.slice(0, limit)) {
+    const event: Event8K = {
+      companyName: filing.companyName,
+      cik: filing.cik,
+      item,
+      itemDescription: ITEM_DESCRIPTIONS[item] ?? `Item ${item}`,
+      filingDate: filing.filedAt,
+      accessionNo: filing.accessionNo,
+      documentUrl: filing.documentUrl,
+    };
+
+    // Extract ticker from company name if available (pattern: "COMPANY NAME (TICKER)")
+    const tickerMatch = filing.companyName.match(/\(([A-Z]{1,6})\)/);
+    if (tickerMatch) event.ticker = tickerMatch[1];
+
+    // For Item 5.02, try to extract people from the filing text
+    if (item === "5.02") {
+      try {
+        await new Promise(r => setTimeout(r, RATE_LIMIT_MS));
+        const docR = await edgarFetch(filing.documentUrl);
+        if (docR.ok) {
+          const text = await docR.text();
+          event.people = extractPeopleFrom502(text);
+          // Extract a short excerpt
+          const idx = text.toLowerCase().indexOf("item 5.02");
+          if (idx >= 0) {
+            event.excerpt = text.slice(idx, idx + 500).replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
+          }
+        }
+      } catch { /* skip extraction */ }
+    }
+
+    events.push(event);
+  }
+
+  return events;
+}
+
+/**
+ * Extract people from Item 5.02 filing text.
+ */
+function extractPeopleFrom502(html: string): Event8K["people"] {
+  const text = html.replace(/<[^>]+>/g, " ").replace(/\s+/g, " ");
+  const people: NonNullable<Event8K["people"]> = [];
+  const seen = new Set<string>();
+
+  // Pattern: "appointed X as Y" or "resignation of X" etc.
+  const patterns = [
+    { re: /(?:appoint|elect|nam)\w*\s+([A-Z][a-z]+ (?:[A-Z]\. )?[A-Z][a-z]+(?:\s[A-Z][a-z]+)?)\s+(?:as|to)\s+([^.,]{3,50})/gi, dir: "appointment" as const },
+    { re: /([A-Z][a-z]+ (?:[A-Z]\. )?[A-Z][a-z]+(?:\s[A-Z][a-z]+)?)\s+(?:has been|was)\s+(?:appoint|elect|nam)\w+\s+(?:as|to)\s+([^.,]{3,50})/gi, dir: "appointment" as const },
+    { re: /(?:resign|depart|terminat|retir)\w*\s+(?:of\s+)?([A-Z][a-z]+ (?:[A-Z]\. )?[A-Z][a-z]+(?:\s[A-Z][a-z]+)?)/gi, dir: "departure" as const },
+    { re: /([A-Z][a-z]+ (?:[A-Z]\. )?[A-Z][a-z]+(?:\s[A-Z][a-z]+)?)\s+(?:has\s+)?(?:resign|depart|retir)\w+/gi, dir: "departure" as const },
+  ];
+
+  for (const { re, dir } of patterns) {
+    for (const match of text.matchAll(re)) {
+      const name = match[1]?.trim();
+      const role = match[2]?.trim();
+      if (name && name.length > 4 && name.includes(" ") && !seen.has(name.toLowerCase())) {
+        seen.add(name.toLowerCase());
+        people.push({ name, role_raw: role, direction: dir });
+      }
+    }
+  }
+
+  return people;
+}

package/src/form4.ts

@@ -0,0 +1,143 @@
+/**
+ * Form 4 Insider Transaction Parser
+ *
+ * Extracts officer/director names and trade details from SEC Form 4 filings.
+ * Useful for ownership tracking, officer lookup, and insider-trading analysis workflows.
+ */
+
+import { edgarFetch, RATE_LIMIT_MS } from "./index.js";
+import { lookupCIK } from "./cik.js";
+
+export interface Form4Person {
+  name: string;
+  title: string;
+  isOfficer: boolean;
+  isDirector: boolean;
+  is10PctOwner: boolean;
+  ticker: string;
+  cik: number;
+  /** Transactions (buys/sells) if available */
+  transactions?: Array<{
+    date: string;
+    code: string;  // P=purchase, S=sale, A=award, etc.
+    shares: number;
+    pricePerShare: number;
+    sharesOwned: number;
+  }>;
+  accessionNo: string;
+  filingDate: string;
+}
+
+/**
+ * Fetch Form 4 filers for a ticker.
+ *
+ * Returns officer/director names with their insider transactions.
+ */
+export async function fetchForm4People(
+  ticker: string,
+  opts: { limit?: number } = {}
+): Promise<Form4Person[]> {
+  const cik = await lookupCIK(ticker);
+  if (!cik) return [];
+
+  const cikPadded = String(cik).padStart(10, "0");
+  const url = `https://data.sec.gov/submissions/CIK${cikPadded}.json`;
+
+  const r = await edgarFetch(url);
+  if (!r.ok) return [];
+
+  const data = await r.json() as {
+    filings: {
+      recent: {
+        accessionNumber: string[];
+        form: string[];
+        filingDate: string[];
+        primaryDocument: string[];
+      };
+    };
+  };
+
+  const recent = data?.filings?.recent;
+  if (!recent) return [];
+
+  // Find Form 4 filings
+  const form4Indices: number[] = [];
+  for (let i = 0; i < recent.form.length; i++) {
+    if (recent.form[i] === "4" || recent.form[i] === "4/A") {
+      form4Indices.push(i);
+    }
+  }
+
+  const limit = opts.limit ?? 20;
+  const people: Form4Person[] = [];
+  const seen = new Set<string>();
+
+  for (const idx of form4Indices.slice(0, limit * 2)) {
+    const accNo = recent.accessionNumber[idx];
+    const filingDate = recent.filingDate[idx];
+    const docName = recent.primaryDocument[idx];
+
+    if (!accNo || !docName) continue;
+
+    // Fetch the Form 4 XML
+    const xmlUrl = `https://www.sec.gov/Archives/edgar/data/${cik}/${accNo.replace(/-/g, "")}/${docName}`;
+
+    try {
+      await new Promise(r => setTimeout(r, RATE_LIMIT_MS));
+      const xmlR = await edgarFetch(xmlUrl, {
+        headers: { Accept: "application/xml,text/xml,text/html" } as Record<string, string>,
+      });
+      if (!xmlR.ok) continue;
+
+      const xmlText = await xmlR.text();
+
+      // Extract reporter name
+      const nameMatch = xmlText.match(/<rptOwnerName>([^<]+)/);
+      const titleMatch = xmlText.match(/<officerTitle>([^<]+)/);
+      const isOfficer = /<isOfficer>true/i.test(xmlText) || /<isOfficer>1/.test(xmlText);
+      const isDirector = /<isDirector>true/i.test(xmlText) || /<isDirector>1/.test(xmlText);
+      const is10Pct = /<isTenPercentOwner>true/i.test(xmlText) || /<isTenPercentOwner>1/.test(xmlText);
+
+      if (!nameMatch) continue;
+
+      const rawName = nameMatch[1].trim();
+      const key = rawName.toLowerCase();
+      if (seen.has(key)) continue;
+      seen.add(key);
+
+      // Extract transactions
+      const transactions: Form4Person["transactions"] = [];
+      const txMatches = xmlText.matchAll(
+        /<transactionDate>.*?<value>([^<]+).*?<transactionCoding>.*?<transactionCode>([^<]+).*?<transactionAmounts>.*?<transactionShares>.*?<value>([^<]+).*?<transactionPricePerShare>.*?<value>([^<]*)/gs
+      );
+      for (const tx of txMatches) {
+        transactions.push({
+          date: tx[1]?.trim() || filingDate,
+          code: tx[2]?.trim() || "?",
+          shares: parseFloat(tx[3]?.trim() || "0"),
+          pricePerShare: parseFloat(tx[4]?.trim() || "0"),
+          sharesOwned: 0,
+        });
+      }
+
+      people.push({
+        name: rawName,
+        title: titleMatch?.[1]?.trim() || (isDirector ? "Director" : "Officer"),
+        isOfficer,
+        isDirector,
+        is10PctOwner: is10Pct,
+        ticker: ticker.toUpperCase(),
+        cik,
+        transactions: transactions.length ? transactions : undefined,
+        accessionNo: accNo,
+        filingDate,
+      });
+
+      if (people.length >= limit) break;
+    } catch {
+      continue;
+    }
+  }
+
+  return people;
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+/**
+ * edgar-client
+ *
+ * Unified SEC EDGAR client. Zero API key needed — all public data.
+ *
+ * Modules:
+ *   - cik: Ticker → CIK resolution (cached)
+ *   - efts: EDGAR Full-Text Search (8-K, 10-K, DEF 14A, etc.)
+ *   - xbrl: XBRL financial time series (revenue, income, capex, etc.)
+ *   - form4: Insider transaction parsing (officer/director names + trades)
+ *   - filing8k: 8-K item extraction (5.02 exec transitions, 2.04 debt, 1.01 M&A)
+ *
+ * Rate limit: SEC allows 10 req/sec with proper User-Agent.
+ * All functions enforce a courtesy delay.
+ */
+
+export { lookupCIK, lookupTicker, loadTickerMap, type CIKEntry } from "./cik.js";
+export { searchFilings, type FilingSearchResult } from "./efts.js";
+export { fetchFinancials, type FinancialSeries } from "./xbrl.js";
+export { fetchForm4People, type Form4Person } from "./form4.js";
+export { fetch8KEvents, type Event8K } from "./filing8k.js";
+
+/** Shared EDGAR headers — SEC requires contact info in User-Agent */
+export const EDGAR_HEADERS = {
+  "User-Agent": "edgar-client/0.1.0 (opensource@example.com)",
+  "Accept": "application/json",
+  "Accept-Encoding": "gzip, deflate",
+};
+
+/** Courtesy delay between requests (ms) — SEC rate limit is 10/sec */
+export const RATE_LIMIT_MS = 120;
+
+export async function edgarFetch(url: string, init?: RequestInit): Promise<Response> {
+  const headers = { ...EDGAR_HEADERS, ...(init?.headers as Record<string, string> ?? {}) };
+  return fetch(url, { ...init, headers, signal: init?.signal ?? AbortSignal.timeout(30000) });
+}

package/src/xbrl.ts

@@ -0,0 +1,99 @@
+/**
+ * XBRL Financial Time Series
+ *
+ * Fetches quarterly financial data from SEC EDGAR's XBRL companyfacts API.
+ * No API key needed. Returns structured time series for fingerprinting.
+ */
+
+import { edgarFetch, RATE_LIMIT_MS } from "./index.js";
+import { lookupCIK } from "./cik.js";
+
+export interface FinancialSeries {
+  ticker: string;
+  concept: string;
+  unit: string;
+  data: Array<{ date: string; value: number; form: string }>;
+}
+
+/** Core financial concepts to fetch */
+const CORE_CONCEPTS = [
+  "us-gaap/Revenues",
+  "us-gaap/RevenueFromContractWithCustomerExcludingAssessedTax",
+  "us-gaap/NetIncomeLoss",
+  "us-gaap/OperatingIncomeLoss",
+  "us-gaap/GrossProfit",
+  "us-gaap/CostOfGoodsAndServicesSold",
+  "us-gaap/InventoriesNet",
+  "us-gaap/Assets",
+  "us-gaap/CapitalExpendituresIncurredButNotYetPaid",
+  "us-gaap/PaymentsToAcquirePropertyPlantAndEquipment",
+  "us-gaap/OperatingCashFlow",
+  "us-gaap/NetCashProvidedByOperatingActivities",
+  "us-gaap/EarningsPerShareDiluted",
+];
+
+/**
+ * Fetch XBRL financial data for a ticker.
+ *
+ * Returns quarterly time series for core financial concepts.
+ * Falls back to alternate concept names (e.g. different revenue labels).
+ */
+export async function fetchFinancials(ticker: string): Promise<FinancialSeries[]> {
+  const cik = await lookupCIK(ticker);
+  if (!cik) return [];
+
+  const cikPadded = String(cik).padStart(10, "0");
+  const url = `https://data.sec.gov/api/xbrl/companyfacts/CIK${cikPadded}.json`;
+
+  const r = await edgarFetch(url);
+  if (!r.ok) return [];
+
+  const data = await r.json() as {
+    facts: Record<string, Record<string, {
+      units: Record<string, Array<{
+        end: string; val: number; form: string; fp: string; fy: number;
+      }>>;
+    }>>;
+  };
+
+  const results: FinancialSeries[] = [];
+
+  for (const conceptPath of CORE_CONCEPTS) {
+    const [taxonomy, concept] = conceptPath.split("/");
+    const conceptData = data?.facts?.[taxonomy]?.[concept];
+    if (!conceptData) continue;
+
+    // Prefer USD units
+    const units = conceptData.units;
+    const unitKey = units["USD"] ? "USD" : units["USD/shares"] ? "USD/shares" : Object.keys(units)[0];
+    if (!unitKey || !units[unitKey]) continue;
+
+    // Filter to quarterly (10-Q) and annual (10-K) filings
+    const points = units[unitKey]
+      .filter(p => p.form === "10-Q" || p.form === "10-K")
+      .filter(p => p.end && !isNaN(p.val))
+      .map(p => ({ date: p.end, value: p.val, form: p.form }))
+      .sort((a, b) => a.date.localeCompare(b.date));
+
+    // Deduplicate by date (keep latest filing)
+    const seen = new Set<string>();
+    const deduped = [];
+    for (let i = points.length - 1; i >= 0; i--) {
+      if (!seen.has(points[i].date)) {
+        seen.add(points[i].date);
+        deduped.unshift(points[i]);
+      }
+    }
+
+    if (deduped.length >= 4) {
+      results.push({
+        ticker: ticker.toUpperCase(),
+        concept,
+        unit: unitKey,
+        data: deduped,
+      });
+    }
+  }
+
+  return results;
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}