Installation

Requirements

• Node.js 24 or newer. Both @xbbg/xnews and @xbbg/xnews-langgraph declare "engines": { "node": ">=24" }.
• ESM only. The package ships ES modules from dist/ with TypeScript declarations and has no CommonJS build.
• No runtime dependencies. Parsing, decompression, spreadsheet, and document decoding are built in. Only the optional transcription features call external programs (see Optional external tools).

Install

npm

npm install @xbbg/xnews

bun

bun add @xbbg/xnews

pnpm

pnpm add @xbbg/xnews

These docs were written against @xbbg/xnews 0.2.2 and @xbbg/xnews-langgraph 0.2.3. Release notes for every version are on the changelog.

Entry points

Import path	Contents	Network code
@xbbg/xnews	Everything: feed builders, watchers, every provider's fetchers, URL builders, and parsers, the data/event/works lanes, document extraction, OCR, and ASR	Yes
@xbbg/xnews/catalog	URL builders for every provider, FIXED_FEEDS, CENTRAL_BANK_NEWS_PROVIDERS, CENTRAL_BANK_RESEARCH_PROVIDERS, PROVIDER_POLICIES, WORKS_PROVIDER_POLICIES, parsePublishedAt, and the version constants	No. Its import graph never reaches the fetch layer
@xbbg/xnews/parsers	Pure parsers for every provider, parseRssItems/parseAtomEntries, subjectMatcher, classifyMarketEvent, readZipEntries, readXlsx, parseCsvRecords/parseCsvTable, and parsePublishedAt	Imports the fetch layer, but nothing in it dials
@xbbg/xnews/asr	Moonshine and OpenRouter transcription backends, transcribePcmStream, and transcribeYoutubeRealtime	Yes (OpenRouter backend, YouTube decoding)

The root export re-exports the /parsers and /asr APIs and nearly all of /catalog, so import { parsePublishedAt } from "@xbbg/xnews" also works. The exception is eight research policy constants (NBER_PROVIDER_POLICY, CROSSREF_PROVIDER_POLICY, and similar) that only /catalog exports by name; the same records are available from the root as PROVIDER_POLICIES["nber"] and so on. Use /catalog when you want xnews's endpoint knowledge but your own governed transport, and /asr when a transcription-only consumer should not bundle feed code.

import { FIXED_FEEDS, PROVIDER_POLICIES, parsePublishedAt } from "@xbbg/xnews/catalog";

console.log(Object.keys(FIXED_FEEDS).length); // 68 fixed feeds in 0.2.2
console.log(PROVIDER_POLICIES["sec-edgar"]?.maxRequestsPerSecond); // 10
console.log(parsePublishedAt("Tue, 02 Jun 2026 14:30:00 GMT"));
// { instant: "2026-06-02T14:30:00.000Z", format: "rfc_822" }

CommonJS callers

There is no require() entry point. From CommonJS code, load the package with a dynamic import():

// CommonJS module (.cjs)
async function main() {
  const { buildTopicNewsFeed } = await import("@xbbg/xnews");
  const items = await buildTopicNewsFeed({ query: "bank capital rules", limit: 5 });
  console.log(items.map((item) => item.title));
}

main();

TypeScript

Declarations ship with the package. Use a module resolution mode that understands package exports so the subpaths resolve:

{
  "compilerOptions": {
    "target": "ES2024",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "types": ["node"]
  }
}

"module": "ESNext" with "moduleResolution": "Bundler" also works. The declarations reference web-platform globals such as RequestInit, Response, and AbortSignal; install @types/node (or add the DOM lib) so they resolve. Every sample in these docs typechecks under strict against the published 0.2.2 declarations.

Optional external tools

Feature	What you install separately
Realtime YouTube transcription	yt-dlp and FFmpeg on PATH (or pass ytDlpCommand / ffmpegCommand)
Local Moonshine transcription	Python with the moonshine-voice package importable; model weights download on first use
Hosted transcription	An OpenRouter API key (createOpenRouterAsrBackend)
OCR for scanned PDFs	Any OpenAI-compatible /v1/chat/completions vision endpoint (extractText(file, { ocr }))
LangChain/LangGraph integration	@xbbg/xnews-langgraph and its peers (see below)

Everything else (news, research, data, events, catalogs, document text) runs on Node.js alone.

Companion package

@xbbg/xnews-langgraph declares the core and LangChain packages as peer dependencies and does not choose a model provider:

npm install @xbbg/xnews-langgraph @xbbg/xnews @langchain/core @langchain/langgraph langchain zod

Supported peer ranges for 0.2.3: @xbbg/xnews ^0.2.2, @langchain/core ^1.2.9, @langchain/langgraph ^1.4.12, langchain ^1.5.10, and zod ^3.25.76 || ^4.2.0.

Next steps

• Quick Start: build your first feed and read the diagnostics.
• Transport & Security: inject your own fetch, set timeouts, and cap response sizes.
• API Reference: every export with its signature.