@lexbuild/fr 1.14.0

package/README.md

@@ -0,0 +1,231 @@
+# @lexbuild/fr
+
+[![npm](https://img.shields.io/npm/v/%40lexbuild%2Ffr?style=for-the-badge)](https://www.npmjs.com/package/@lexbuild/fr)
+[![license](https://img.shields.io/github/license/chris-c-thomas/LexBuild?style=for-the-badge)](https://github.com/chris-c-thomas/LexBuild/blob/main/LICENSE)
+
+Converts [Federal Register](https://www.federalregister.gov/) XML into structured Markdown optimized for AI, RAG pipelines, and semantic search. Downloads documents via the FederalRegister.gov API with rich JSON metadata (agencies, CFR references, docket IDs, effective dates) alongside XML full text.
+
+> **Tip:** For command-line usage, install [`@lexbuild/cli`](https://www.npmjs.com/package/@lexbuild/cli) instead. This package is the programmatic API.
+
+## Install
+
+```bash
+npm install @lexbuild/fr
+# or
+pnpm add @lexbuild/fr
+```
+
+**Peer dependency:** [`@lexbuild/core`](https://www.npmjs.com/package/@lexbuild/core) (installed automatically via workspace protocol in the monorepo).
+
+## Quick Start
+
+### Download and Convert
+
+```ts
+import { downloadFrDocuments, convertFrDocuments } from "@lexbuild/fr";
+
+// Download last 30 days of Federal Register documents
+const download = await downloadFrDocuments({
+  output: "./downloads/fr",
+  from: "2026-03-01",
+  to: "2026-03-31",
+});
+console.log(`Downloaded ${download.documentsDownloaded} documents`);
+
+// Convert to Markdown
+const result = await convertFrDocuments({
+  input: "./downloads/fr",
+  output: "./output",
+  linkStyle: "plaintext",
+  dryRun: false,
+});
+
+console.log(`${result.documentsConverted} documents, ${result.totalTokenEstimate} est. tokens`);
+```
+
+### Download by Document Type
+
+```ts
+import { downloadFrDocuments } from "@lexbuild/fr";
+
+// Download only final rules from Q1 2026
+const result = await downloadFrDocuments({
+  output: "./downloads/fr",
+  from: "2026-01-01",
+  to: "2026-03-31",
+  types: ["RULE"],
+});
+```
+
+### Download a Single Document
+
+```ts
+import { downloadSingleFrDocument } from "@lexbuild/fr";
+
+const file = await downloadSingleFrDocument("2026-06029", "./downloads/fr");
+console.log(`XML: ${file.xmlPath}`);
+console.log(`JSON: ${file.jsonPath}`);
+```
+
+### Convert with Type Filtering
+
+```ts
+import { convertFrDocuments } from "@lexbuild/fr";
+
+const result = await convertFrDocuments({
+  input: "./downloads/fr",
+  output: "./output",
+  linkStyle: "plaintext",
+  dryRun: false,
+  from: "2026-01-01",
+  to: "2026-03-31",
+  types: ["RULE", "PRORULE"], // Only rules and proposed rules
+});
+```
+
+## API Reference
+
+### Functions
+
+| Export | Description |
+|--------|-------------|
+| `convertFrDocuments(options)` | Convert FR XML files to Markdown |
+| `downloadFrDocuments(options)` | Download FR documents by date range from the API |
+| `downloadSingleFrDocument(number, output)` | Download a single document by document number |
+| `buildFrApiListUrl(from, to, page, types?)` | Build the API listing URL for a date range |
+| `buildFrFrontmatter(node, context, xmlMeta, jsonMeta?)` | Build frontmatter from AST node and metadata |
+| `buildFrOutputPath(number, date, root)` | Build output file path for a document |
+| `buildFrDownloadXmlPath(number, date, root)` | Build download XML file path |
+| `buildFrDownloadJsonPath(number, date, root)` | Build download JSON file path |
+
+### Types
+
+| Export | Description |
+|--------|-------------|
+| `FrConvertOptions` | Options for `convertFrDocuments()` — input, output, link style, date/type filters |
+| `FrConvertResult` | Conversion result — documents converted, files, token estimate |
+| `FrDownloadOptions` | Options for `downloadFrDocuments()` — output, date range, types, limit |
+| `FrDownloadResult` | Download result — documents downloaded, files, bytes, skipped, failed |
+| `FrDownloadedFile` | Single downloaded file metadata (XML path, JSON path, size) |
+| `FrDownloadFailure` | Failed download metadata (document number, error) |
+| `FrDownloadProgress` | Progress info for the download callback |
+| `FrDocumentType` | `"RULE" \| "PRORULE" \| "NOTICE" \| "PRESDOCU"` |
+| `FrDocumentJsonMeta` | JSON metadata structure from the FederalRegister.gov API |
+| `FrDocumentXmlMeta` | Metadata extracted from FR XML during SAX parsing |
+
+### Classes
+
+| Export | Description |
+|--------|-------------|
+| `FrASTBuilder` | SAX-to-AST builder for FR GPO/SGML XML. Emits one section-level node per document. |
+
+### Constants
+
+| Export | Description |
+|--------|-------------|
+| `FR_DOCUMENT_ELEMENTS` | Set of document type elements (`RULE`, `NOTICE`, etc.) |
+| `FR_DOCUMENT_TYPE_MAP` | Map from element names to normalized type strings |
+| `FR_EMPHASIS_MAP` | Map from `E` element `T` attribute to inline formatting types |
+| `FR_HD_SOURCE_TO_DEPTH` | Map from `HD` `SOURCE` attribute to heading depth |
+
+## Output
+
+Each document produces one Markdown file organized by publication date:
+
+| Output Path | Description |
+|---|---|
+| `fr/2026/03/2026-06029.md` | Individual document |
+
+No granularity options — FR documents are already atomic (one file per document).
+
+### Frontmatter
+
+FR documents include source-specific metadata alongside standard LexBuild fields. When a JSON sidecar from the API is available, frontmatter is enriched with structured agency, CFR reference, docket, and date information:
+
+```yaml
+---
+identifier: "/us/fr/2026-06029"
+source: "fr"
+legal_status: "authoritative_unofficial"
+title: "Meeting of the Advisory Board on Radiation and Worker Health"
+title_number: 0
+title_name: "Federal Register"
+section_number: "2026-06029"
+positive_law: false
+currency: "2026-03-30"
+last_updated: "2026-03-30"
+agency: "Health and Human Services Department"
+document_number: "2026-06029"
+document_type: "notice"
+fr_citation: "91 FR 15619"
+fr_volume: 91
+publication_date: "2026-03-30"
+agencies:
+  - "Health and Human Services Department"
+  - "Centers for Disease Control and Prevention"
+fr_action: "Notice of meeting."
+---
+```
+
+Rules and proposed rules include additional fields:
+
+```yaml
+cfr_references:
+  - "10 CFR Part 53"
+  - "10 CFR Part 50"
+docket_ids:
+  - "NRC-2019-0062"
+rin: "3150-AK31"
+effective_date: "2026-04-29"
+```
+
+## Data Source
+
+| Field | Detail |
+|-------|--------|
+| **API** | `federalregister.gov/api/v1/` |
+| **Authentication** | None required |
+| **Rate limits** | No documented limits |
+| **Coverage** | JSON metadata from 1994, XML full text from 2000 |
+| **Update cadence** | Daily (each business day) |
+| **Volume** | ~28,000-31,000 documents/year |
+| **Legal status** | Unofficial — only authenticated PDF has legal standing |
+
+The downloader fetches both JSON metadata (40+ structured fields) and XML full text per document. Large date ranges are automatically chunked by month to stay under the API's 10,000-result cap per query.
+
+## Document Types
+
+| Type | Element | Annual Volume | Description |
+|------|---------|---------------|-------------|
+| Notice | `NOTICE` | ~22,000-25,000 | Agency announcements, meetings, information collections |
+| Rule | `RULE` | ~3,000-3,200 | Final rules and regulations |
+| Proposed Rule | `PRORULE` | ~1,700-2,100 | Notices of proposed rulemaking (NPRMs) |
+| Presidential Document | `PRESDOCU` | ~300-470 | Executive orders, memoranda, proclamations |
+
+## Compatibility
+
+- **Node.js** >= 22
+- **ESM only** — no CommonJS build
+- **TypeScript** — ships `.d.ts` type declarations
+
+## Monorepo Context
+
+Part of the [LexBuild](https://github.com/chris-c-thomas/LexBuild) monorepo. Depends on `@lexbuild/core` for XML parsing, AST types, and Markdown rendering.
+
+```bash
+pnpm turbo build --filter=@lexbuild/fr
+pnpm turbo test --filter=@lexbuild/fr
+```
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [`@lexbuild/cli`](https://www.npmjs.com/package/@lexbuild/cli) | CLI tool — the easiest way to use LexBuild |
+| [`@lexbuild/core`](https://www.npmjs.com/package/@lexbuild/core) | Shared parsing, AST, and rendering infrastructure |
+| [`@lexbuild/usc`](https://www.npmjs.com/package/@lexbuild/usc) | U.S. Code (USLM XML) converter |
+| [`@lexbuild/ecfr`](https://www.npmjs.com/package/@lexbuild/ecfr) | eCFR (Code of Federal Regulations) converter |
+
+## License
+
+[MIT](https://github.com/chris-c-thomas/LexBuild/blob/main/LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,414 @@
+import { LevelNode, EmitContext, Attributes, InlineType, FrontmatterData } from '@lexbuild/core';
+
+/**
+ * Federal Register AST Builder — converts SAX events from FR XML into AST nodes.
+ *
+ * Follows the stack-based pattern from the eCFR builder but adapted for FR's
+ * flat, document-centric structure. Each FR document (RULE, NOTICE, PRORULE,
+ * PRESDOCU) becomes a single section-level LevelNode emitted via onEmit.
+ *
+ * FR XML is GPO/SGML-derived with no namespace. It shares inline formatting
+ * (E T="nn", SU, FTNT) with eCFR but uses a different document structure:
+ * preamble (PREAMB) → supplementary info (SUPLINF) → signature (SIG).
+ */
+
+/** Options for configuring the FR AST builder */
+interface FrASTBuilderOptions {
+    /** Callback when a completed document node is ready */
+    onEmit: (node: LevelNode, context: EmitContext) => void | Promise<void>;
+}
+/** Metadata extracted from the FR document XML during parsing */
+interface FrDocumentXmlMeta {
+    /** Document type element name (RULE, NOTICE, etc.) */
+    documentType: string;
+    /** Normalized document type (rule, proposed_rule, etc.) */
+    documentTypeNormalized: string;
+    /** Agency name from AGENCY element */
+    agency?: string | undefined;
+    /** Sub-agency name from SUBAGY element */
+    subAgency?: string | undefined;
+    /** Subject/title from SUBJECT element */
+    subject?: string | undefined;
+    /** CFR citation from CFR element */
+    cfrCitation?: string | undefined;
+    /** Regulation Identifier Number from RIN element */
+    rin?: string | undefined;
+    /** FR document number extracted from FRDOC text */
+    documentNumber?: string | undefined;
+}
+/**
+ * Federal Register AST Builder.
+ *
+ * Consumes SAX events and produces LexBuild AST nodes. Each FR document
+ * (RULE, NOTICE, PRORULE, PRESDOCU) is emitted as a single section-level
+ * LevelNode via the onEmit callback.
+ */
+declare class FrASTBuilder {
+    private readonly options;
+    private readonly stack;
+    /** Depth inside fully-ignored elements (CNTNTS, GPH) */
+    private ignoredContainerDepth;
+    /** Metadata extracted from current document */
+    private currentDocMeta;
+    /** All document metadata collected during parsing */
+    private readonly documentMetas;
+    constructor(options: FrASTBuilderOptions);
+    /** Get metadata for all documents parsed so far */
+    getDocumentMetas(): readonly FrDocumentXmlMeta[];
+    /** Handle SAX open element */
+    onOpenElement(name: string, attrs: Attributes): void;
+    /** Handle SAX close element */
+    onCloseElement(name: string): void;
+    /** Handle SAX text content */
+    onText(text: string): void;
+    private openDocument;
+    private closeDocument;
+    private closePreambleMeta;
+    private openHeading;
+    private closeHeading;
+    private openContent;
+    private closeContent;
+    private openInline;
+    private closeInline;
+    private openNote;
+    private closeNote;
+    private openRegtext;
+    private closeRegtext;
+    private openSignature;
+    private closeSignature;
+    private openTableElement;
+    private closeTableElement;
+    private closeGpoTable;
+    private closeTableHeader;
+    private closeTableRow;
+    private closeTableCell;
+    private closeFrdoc;
+    private addToDocument;
+    private findParentDocument;
+    private findParentNote;
+    private findTableFrame;
+    private findFrame;
+    private popFrame;
+}
+
+/**
+ * Federal Register XML element classification.
+ *
+ * The FR XML is GPO/SGML-derived with no namespace. It shares many
+ * inline formatting elements with eCFR (E T="nn", SU, FTNT) but uses
+ * a flat document-centric structure rather than a hierarchical DIV system.
+ *
+ * Each FR document (RULE, PRORULE, NOTICE, PRESDOCU) contains a preamble
+ * (PREAMB) with structured metadata, supplementary information (SUPLINF)
+ * with the document body, and optional regulatory text (REGTEXT).
+ */
+
+/** FR document type element names as a const tuple — single source of truth */
+declare const FR_DOCUMENT_TYPE_KEYS: readonly ["RULE", "PRORULE", "NOTICE", "PRESDOCU"];
+/** FR document types supported by the API and XML */
+type FrDocumentType = (typeof FR_DOCUMENT_TYPE_KEYS)[number];
+/** Top-level document elements — each becomes an emitted section-level node */
+declare const FR_DOCUMENT_ELEMENTS: Set<string>;
+/** Container elements that group documents within daily issues */
+declare const FR_SECTION_CONTAINERS: Set<string>;
+/** Map from document element name to normalized document type string */
+declare const FR_DOCUMENT_TYPE_MAP: Readonly<Record<string, string>>;
+/** Preamble section elements containing structured content */
+declare const FR_PREAMBLE_SECTIONS: Set<string>;
+/** Preamble metadata elements — text extracted for frontmatter */
+declare const FR_PREAMBLE_META_ELEMENTS: Set<string>;
+/** Elements that contain paragraph text */
+declare const FR_CONTENT_ELEMENTS: Set<string>;
+/** Heading element — level determined by SOURCE attribute */
+declare const FR_HEADING_ELEMENT = "HD";
+/**
+ * Map from HD SOURCE attribute to heading depth.
+ * HED = top-level (section-like), HD1 = subsection, etc.
+ */
+declare const FR_HD_SOURCE_TO_DEPTH: Readonly<Record<string, number>>;
+/** Inline formatting elements */
+declare const FR_INLINE_ELEMENTS: Set<string>;
+/**
+ * Map from E element T attribute to InlineType.
+ * Duplicated from eCFR — source packages must not import each other.
+ */
+declare const FR_EMPHASIS_MAP: Readonly<Record<string, InlineType>>;
+/** Regulatory text amendment elements (within SUPLINF) */
+declare const FR_REGTEXT_ELEMENTS: Set<string>;
+/** Signature block elements */
+declare const FR_SIGNATURE_ELEMENTS: Set<string>;
+/** Presidential document subtype containers */
+declare const FR_PRESIDENTIAL_SUBTYPES: Set<string>;
+/** Footnote and editorial note elements */
+declare const FR_NOTE_ELEMENTS: Set<string>;
+/** Block-level content wrappers */
+declare const FR_BLOCK_ELEMENTS: Set<string>;
+/** GPOTABLE elements */
+declare const FR_TABLE_ELEMENTS: Set<string>;
+/** Elements whose entire subtree should be skipped */
+declare const FR_IGNORE_ELEMENTS: Set<string>;
+/** Self-contained elements to skip — metadata extracted elsewhere or irrelevant */
+declare const FR_SKIP_ELEMENTS: Set<string>;
+/** Transparent wrappers — pass through without creating frames */
+declare const FR_PASSTHROUGH_ELEMENTS: Set<string>;
+
+/**
+ * Federal Register frontmatter builder.
+ *
+ * Constructs FrontmatterData from an emitted FR AST node, its context,
+ * and optional JSON metadata from the FederalRegister.gov API.
+ */
+
+/**
+ * Metadata from the FederalRegister.gov API JSON response.
+ * Stored as a sidecar `.json` file alongside each `.xml` download.
+ */
+interface FrDocumentJsonMeta {
+    /** FR document number (e.g., "2026-06029") */
+    document_number: string;
+    /** Document type (Rule, Proposed Rule, Notice, Presidential Document) */
+    type: string;
+    /** Document title */
+    title: string;
+    /** Publication date (YYYY-MM-DD) */
+    publication_date: string;
+    /** Full FR citation (e.g., "91 FR 14523") */
+    citation: string;
+    /** FR volume number */
+    volume: number;
+    /** Start page number */
+    start_page: number;
+    /** End page number */
+    end_page: number;
+    /** Agencies with hierarchy info */
+    agencies: Array<{
+        name: string;
+        id: number;
+        slug: string;
+        parent_id?: number | null;
+        raw_name?: string;
+    }>;
+    /** CFR title/part references */
+    cfr_references: Array<{
+        title: number;
+        part: number;
+    }>;
+    /** Docket identifiers */
+    docket_ids: string[];
+    /** Regulation Identifier Numbers */
+    regulation_id_numbers: string[];
+    /** Effective date (YYYY-MM-DD) */
+    effective_on?: string | null;
+    /** Comment period end date (YYYY-MM-DD) */
+    comments_close_on?: string | null;
+    /** Action description (e.g., "Final rule.") */
+    action?: string | null;
+    /** Document abstract */
+    abstract?: string | null;
+    /** Whether the document is significant */
+    significant?: boolean | null;
+    /** Topics/keywords */
+    topics: string[];
+    /** URL to full text XML */
+    full_text_xml_url: string;
+}
+/**
+ * Build FrontmatterData from an FR document node with optional JSON metadata.
+ *
+ * If JSON metadata is available (from the API sidecar file), it enriches
+ * the frontmatter with structured agency, CFR reference, docket, and
+ * date information that isn't available in the XML alone.
+ */
+declare function buildFrFrontmatter(node: LevelNode, _context: EmitContext, xmlMeta: FrDocumentXmlMeta, jsonMeta?: FrDocumentJsonMeta): FrontmatterData;
+
+/**
+ * Output path builder for Federal Register directory structure.
+ *
+ * FR path structure:
+ *   output/fr/{YYYY}/{MM}/{document_number}.md
+ *
+ * Downloads path structure:
+ *   downloads/fr/{YYYY}/{MM}/{document_number}.xml
+ *   downloads/fr/{YYYY}/{MM}/{document_number}.json
+ */
+/**
+ * Build the output file path for an FR document.
+ *
+ * @param documentNumber - FR document number (e.g., "2026-06029")
+ * @param publicationDate - Publication date in YYYY-MM-DD format
+ * @param outputRoot - Output root directory (e.g., "./output")
+ * @returns Full output file path (e.g., "output/fr/2026/03/2026-06029.md")
+ */
+declare function buildFrOutputPath(documentNumber: string, publicationDate: string, outputRoot: string): string;
+/**
+ * Build the download file path for an FR document XML.
+ *
+ * @param documentNumber - FR document number
+ * @param publicationDate - Publication date in YYYY-MM-DD format
+ * @param downloadRoot - Download root directory (e.g., "./downloads/fr")
+ * @returns Full download file path (e.g., "downloads/fr/2026/03/2026-06029.xml")
+ */
+declare function buildFrDownloadXmlPath(documentNumber: string, publicationDate: string, downloadRoot: string): string;
+/**
+ * Build the download file path for an FR document JSON metadata.
+ *
+ * @param documentNumber - FR document number
+ * @param publicationDate - Publication date in YYYY-MM-DD format
+ * @param downloadRoot - Download root directory
+ * @returns Full download file path (e.g., "downloads/fr/2026/03/2026-06029.json")
+ */
+declare function buildFrDownloadJsonPath(documentNumber: string, publicationDate: string, downloadRoot: string): string;
+/**
+ * Build the directory path for a year/month within the FR output structure.
+ */
+declare function buildMonthDir(year: string, month: string, outputRoot: string): string;
+/**
+ * Build the directory path for a year.
+ */
+declare function buildYearDir(year: string, outputRoot: string): string;
+
+/**
+ * Federal Register conversion orchestrator.
+ *
+ * Discovers downloaded FR XML files, parses them with FrASTBuilder,
+ * enriches frontmatter with JSON sidecar metadata, renders via core's
+ * renderDocument, and writes structured Markdown output.
+ *
+ * Processes FR documents in two passes: (1) parse all files and register
+ * identifiers for link resolution, (2) render and write output files.
+ */
+
+/** Options for converting FR documents */
+interface FrConvertOptions {
+    /** Path to input file or directory containing .xml/.json files */
+    input: string;
+    /** Output root directory */
+    output: string;
+    /** Link style for cross-references */
+    linkStyle: "relative" | "canonical" | "plaintext";
+    /** Parse only, don't write files */
+    dryRun: boolean;
+    /** Filter: start date (YYYY-MM-DD) */
+    from?: string | undefined;
+    /** Filter: end date (YYYY-MM-DD) */
+    to?: string | undefined;
+    /** Filter: document types */
+    types?: FrDocumentType[] | undefined;
+}
+/** Result of a conversion operation */
+interface FrConvertResult {
+    /** Number of documents converted */
+    documentsConverted: number;
+    /** Paths of written files */
+    files: string[];
+    /** Total estimated tokens */
+    totalTokenEstimate: number;
+    /** Peak RSS in bytes */
+    peakMemoryBytes: number;
+    /** Whether this was a dry run */
+    dryRun: boolean;
+}
+/**
+ * Convert FR XML documents to Markdown.
+ *
+ * Supports both single-file mode (input is a .xml path) and batch mode
+ * (input is a directory containing year/month/doc.xml structure).
+ */
+declare function convertFrDocuments(options: FrConvertOptions): Promise<FrConvertResult>;
+
+/**
+ * Federal Register API downloader.
+ *
+ * Downloads FR documents (XML + JSON metadata) from the FederalRegister.gov API.
+ * The API provides per-document endpoints, rich JSON metadata, and requires no
+ * authentication. Results are paginated (max 200/page) with a 10,000 result cap
+ * per query — the downloader auto-chunks by month for large date ranges.
+ *
+ * API base: https://www.federalregister.gov/api/v1/
+ */
+
+/** Options for downloading FR documents */
+interface FrDownloadOptions {
+    /** Download directory (e.g., "./downloads/fr") */
+    output: string;
+    /** Start date (YYYY-MM-DD, inclusive) */
+    from: string;
+    /** End date (YYYY-MM-DD, inclusive). Defaults to today. */
+    to?: string | undefined;
+    /** Document types to download. All types if omitted. */
+    types?: FrDocumentType[] | undefined;
+    /** Maximum number of documents to download (for testing) */
+    limit?: number | undefined;
+    /** Delay between XML fetches in milliseconds */
+    fetchDelayMs?: number | undefined;
+    /** Progress callback */
+    onProgress?: ((progress: FrDownloadProgress) => void) | undefined;
+}
+/** Progress info for download callback */
+interface FrDownloadProgress {
+    /** Documents downloaded so far */
+    documentsDownloaded: number;
+    /** Total documents found across all pages */
+    totalDocuments: number;
+    /** Current document number being downloaded */
+    currentDocument: string;
+    /** Current date chunk being processed (YYYY-MM) */
+    currentChunk: string;
+}
+/** A successfully downloaded FR document */
+interface FrDownloadedFile {
+    /** Absolute path to the XML file */
+    xmlPath: string;
+    /** Absolute path to the JSON metadata file */
+    jsonPath: string;
+    /** Document number */
+    documentNumber: string;
+    /** Publication date */
+    publicationDate: string;
+    /** Combined size in bytes (XML + JSON) */
+    size: number;
+}
+/** A failed download */
+interface FrDownloadFailure {
+    /** Document number */
+    documentNumber: string;
+    /** Error message */
+    error: string;
+}
+/** Result of a download operation */
+interface FrDownloadResult {
+    /** Number of documents downloaded */
+    documentsDownloaded: number;
+    /** Paths of downloaded files */
+    files: FrDownloadedFile[];
+    /** Total bytes downloaded */
+    totalBytes: number;
+    /** Date range covered */
+    dateRange: {
+        from: string;
+        to: string;
+    };
+    /** Documents without XML (pre-2000) */
+    skipped: number;
+    /** Documents that failed to download */
+    failed: FrDownloadFailure[];
+}
+/**
+ * Build the API documents listing URL for a date range.
+ */
+declare function buildFrApiListUrl(from: string, to: string, page: number, types?: FrDocumentType[]): string;
+/**
+ * Download FR documents for a date range.
+ *
+ * Automatically chunks large date ranges into month-sized windows to stay
+ * under the API's 10,000 result cap per query.
+ */
+declare function downloadFrDocuments(options: FrDownloadOptions): Promise<FrDownloadResult>;
+/**
+ * Download a single FR document by document number.
+ *
+ * Fetches both the JSON metadata and XML full text.
+ */
+declare function downloadSingleFrDocument(documentNumber: string, output: string): Promise<FrDownloadedFile>;
+
+export { FR_BLOCK_ELEMENTS, FR_CONTENT_ELEMENTS, FR_DOCUMENT_ELEMENTS, FR_DOCUMENT_TYPE_KEYS, FR_DOCUMENT_TYPE_MAP, FR_EMPHASIS_MAP, FR_HD_SOURCE_TO_DEPTH, FR_HEADING_ELEMENT, FR_IGNORE_ELEMENTS, FR_INLINE_ELEMENTS, FR_NOTE_ELEMENTS, FR_PASSTHROUGH_ELEMENTS, FR_PREAMBLE_META_ELEMENTS, FR_PREAMBLE_SECTIONS, FR_PRESIDENTIAL_SUBTYPES, FR_REGTEXT_ELEMENTS, FR_SECTION_CONTAINERS, FR_SIGNATURE_ELEMENTS, FR_SKIP_ELEMENTS, FR_TABLE_ELEMENTS, FrASTBuilder, type FrASTBuilderOptions, type FrConvertOptions, type FrConvertResult, type FrDocumentJsonMeta, type FrDocumentType, type FrDocumentXmlMeta, type FrDownloadFailure, type FrDownloadOptions, type FrDownloadProgress, type FrDownloadResult, type FrDownloadedFile, buildFrApiListUrl, buildFrDownloadJsonPath, buildFrDownloadXmlPath, buildFrFrontmatter, buildFrOutputPath, buildMonthDir, buildYearDir, convertFrDocuments, downloadFrDocuments, downloadSingleFrDocument };