xnews · @xbbg/xnews · latest v0.2.2

Public news, research, and data feeds as typed, normalized records.

xnews is a TypeScript library of pure fetch, parse, and normalize utilities. Point it at a company, a topic, or a watchlist and it fans out across public feeds and APIs, merges duplicates, and returns NewsItem records with per-provider diagnostics. It also reads scheduled data releases, active-event feeds, book catalogs, documents, and YouTube media.

What it is

• A toolkit, not a service. Every call is a plain async function. xnews never opens a connection except through the fetch you give it (default globalThis.fetch).
• Zero runtime dependencies. RSS/Atom, JSON, CSV, ZIP, XLSX, EPUB, PDF, DjVu, and MOBI handling are built in.
• Honest about failure. Feed builders never throw for one bad provider. Each provider reports ok, empty, partial, error, unsupported, or disabled, with warnings, redacted request URLs, timing, and a machine-readable error code.
• Policy-aware. SEC requests require a declared User-Agent, MSRB EMMA requires recorded terms acceptance, keyed APIs require keys, and PROVIDER_POLICIES records rate limits and licensing notes before you schedule anything.

What it is not

xnews does not persist data, schedule jobs, store state, score sentiment, rank materiality, or provide investment advice. Watchers poll and yield new records, but where those records go (database, queue, alerting) is your application's decision. Endpoint access is not a content license: follow each publisher's terms before you reproduce full text.

Four lanes, one status model

News

Dated documents as NewsItem: company, topic, and watchlist feeds over query APIs, fixed RSS/Atom feeds, SEC EDGAR, central banks, and research-paper indexes.

Data

Dated rows as DataRelease: FRED, CFTC Commitments of Traders, FFIEC bank data, DTCC swaps, HMDA, CRA, NIC, and macro, climate, and cyber datasets.

Events

What is in force right now as EventSnapshot: weather alerts, storms, disasters, volcanoes, tsunami messages, airport status, and other active-state feeds.

Works

Undated catalog records as WorkRecord: Open Library, Internet Archive, and mirror-based catalogs, plus file download and text extraction.

Each lane has its own record shape and the same non-throwing envelope (status, warnings, requestUrls, fetchedAt, durationMs, error). Current-state APIs that have no release cadence, such as quotes and prediction markets, are plain typed fetch functions.

A first feed

import { buildCompanyNewsFeedResult } from "@xbbg/xnews";

const result = await buildCompanyNewsFeedResult({
  ticker: "MSFT",
  companyName: "Microsoft",
  secUserAgent: "my-app/1.0 ops@example.com",
  limit: 20,
});

for (const item of result.items) {
  console.log(item.publishedAt, item.provider, item.title);
}

for (const provider of result.providers) {
  console.log(provider.provider, provider.status, provider.itemCount, provider.warnings);
}

The default company sources are sec-edgar, yahoo-finance, google-news, and finviz. The Quick Start walks through the result shape, and the Source Catalog lists all 104 news providers plus the data, event, and works sources.

How a feed request flows

1. 01Normalize the subject

   A company (ticker, name, or CIK) or a topic query. Invalid subjects fail fast with a RangeError.

2. 02Fan out

   Each selected provider is fetched concurrently through one transport chokepoint that enforces timeouts, response-size caps, redirect policy, and SEC/EMMA requirements.

3. 03Filter and annotate

   Date windows are enforced locally, fixed feeds are matched against the subject, and deterministic eventKind/tags hints are added.

4. 04Merge

   Items sharing a canonical URL collapse into one record that keeps seenInProviders and provenance; results are sorted newest first and capped by limit.

Packages

Package	Purpose	Install
@xbbg/xnews	The core library. Root export plus /catalog, /parsers, and /asr subpaths	npm install @xbbg/xnews
@xbbg/xnews-langgraph	LangChain tools, finite LangGraph nodes, and a starter analyst built on xnews	npm install @xbbg/xnews-langgraph plus peers

Both packages are ESM-only, require Node.js 24 or newer, and are Apache-2.0 licensed. Source: underloam/xnews.

Next steps

Installation

Node 24, ESM-only packaging, subpath exports, and TypeScript settings.

Quick Start

Build a company feed, read provider diagnostics, and watch for new items.

Company Feeds

Tickers, CIKs, SEC forms, provider requirements, and filtering.

Research Papers

arXiv, OpenAlex, BIS, NBER, SSRN, Crossref, World Bank, and more.

Economic Data Releases

FRED, CFTC COT, FFIEC bank data, DTCC swaps, and release watchers.

LangGraph Tools

Give agents bounded, redacted access to every xnews lane.

Provider Policies

Keys, User-Agent rules, rate limits, and licensing notes per provider.

API Reference

Generated TypeScript reference for every export of @xbbg/xnews.