API Reference — FeedReader Documentation

class

RSSParser

Parses RSS XML feeds into RSSStory objects. Supports loading multiple feeds concurrently with O(1) deduplication by link URL. Thread-safe — all shared state mutations are serialized on an internal serial queue.

Properties

Property	Type	Description
`delegate`	`RSSParserDelegate?`	Delegate notified when feed loading completes or fails
`stories`	`[RSSStory]`	Read-only. Accumulated stories from all parsed feeds

Methods

Method	Description
`loadFeeds(_ urls: [String])`	Parse stories from multiple feed URLs concurrently. Calls delegate on the main thread when all feeds complete. Cancels any in-flight load from a previous call. Stories are deduplicated by link URL.
`parseData(_ data: Data) → [RSSStory]`	Parse stories from in-memory XML data synchronously. Useful for testing and offline scenarios. Returns an array of parsed stories directly.

Usage

import FeedReaderCore

class MyFeedController: RSSParserDelegate {
    let parser = RSSParser()

    func fetchFeeds() {
        parser.delegate = self
        parser.loadFeeds([
            "https://feeds.bbci.co.uk/news/world/rss.xml",
            "https://techcrunch.com/feed/"
        ])
    }

    func parserDidFinishLoading(stories: [RSSStory]) {
        // Stories from all feeds, deduplicated
        print("Loaded \(stories.count) stories")
    }

    func parserDidFailWithError(_ error: Error?) {
        print("Feed load failed: \(error?.localizedDescription ?? "unknown")")
    }
}
            

protocol

RSSParserDelegate

Delegate protocol for receiving RSS parsing results. Callbacks are always delivered on the main thread.

Required Methods

Method	Description
`parserDidFinishLoading(stories: [RSSStory])`	Called when all requested feeds have finished loading. The stories array contains deduplicated results from all feeds.
`parserDidFailWithError(_ error: Error?)`	Called when a feed fails to load. The error may be nil for non-HTTP errors.

class

RSSStory

Represents a single parsed RSS story with title, body, link, and optional image URL. Provides URL validation and HTML sanitization. Conforms to NSObject and Sendable.

Properties

Property	Type	Description
`title`	`String`	The story headline
`body`	`String`	The story description with HTML tags stripped and entities decoded
`link`	`String`	The story's unique URL (used for equality and deduplication)
`imagePath`	`String?`	Optional thumbnail image URL (only set if URL passes safety validation)

Initializer

public init?(
    title: String,
    body: String,
    link: String,
    imagePath: String? = nil
)
            

Returns nil if:

title is empty
body is empty after HTML stripping
link is not a valid HTTP/HTTPS URL

Static Methods

Method	Description
`isSafeURL(_ urlString: String?) → Bool`	Validates that a URL uses only allowed schemes (`http`, `https`). Rejects `javascript:`, `file:`, `data:`, and other unsafe schemes.
`stripHTML(_ html: String) → String`	Strips HTML tags via regex and decodes common HTML entities (`&`, `<`, `>`, `"`, `'`, ` `).

Equality

Two RSSStory instances are equal if their link properties match. This is how deduplication works across multiple feeds.

class

FeedItem

Represents an RSS feed source with a name, URL, and enabled state. Conforms to NSSecureCoding for persistent storage and Sendable for thread safety.

Properties

Property	Type	Description
`name`	`String`	Display name for the feed
`url`	`String`	RSS feed URL string
`isEnabled`	`Bool`	Whether the feed is currently enabled for fetching
`identifier`	`String`	Computed. Lowercased URL used for deduplication

Initializer

public init(
    name: String,
    url: String,
    isEnabled: Bool = false
)
            

Static Properties

Property	Description
`presets: [FeedItem]`	10 built-in feed sources: BBC World News, BBC Technology, BBC Science, BBC Business, NPR News, Reuters World, TechCrunch, Ars Technica, Hacker News, The Verge

Usage

// Use built-in presets
let feeds = FeedItem.presets
let enabledUrls = feeds
    .filter { $0.isEnabled }
    .map { $0.url }

// Create custom feed
let custom = FeedItem(
    name: "My Blog",
    url: "https://myblog.com/rss.xml",
    isEnabled: true
)
            

enum

NetworkReachability

Provides a simple check for network connectivity using SystemConfiguration. Uses SCNetworkReachability to check for a default network route.

Static Methods

Method	Description
`isConnected() → Bool`	Returns `true` if the device currently has a network route available. Does not guarantee that a specific host is reachable — only that the system believes a route exists.

Usage

import FeedReaderCore

if NetworkReachability.isConnected() {
    parser.loadFeeds(feedUrls)
} else {
    // Load from cache or show offline UI
    showCachedStories()
}
            

ArticleArchiveExporter

Exports RSSStory objects as self-contained HTML archive files for offline reading, sharing, or long-term preservation. Supports single and batch export with 4 visual themes (light, dark, sepia, newspaper).

Initialization

let exporter = ArticleArchiveExporter(options: .default)

// Or with custom options:
var opts = ArticleArchiveExporter.ExportOptions(
    theme: .sepia,
    includeMetadata: true,
    includeTableOfContents: true,
    includeWordCount: true,
    includeEstimatedReadTime: true
)
let exporter = ArticleArchiveExporter(options: opts)
        

Types

Type	Description
`Theme`	Visual theme enum: `.light`, `.dark`, `.sepia`, `.newspaper`. Each provides `backgroundColor`, `textColor`, `accentColor`, and `fontFamily`.
`ExportOptions`	Configures theme, metadata inclusion, table of contents, word count, read time, and optional custom CSS.
`ExportResult`	Contains the exported `filename`, `htmlContent`, `articleCount`, `totalWordCount`, and `exportDate`.

Methods

Method	Description
`exportArticle(_ story: RSSStory) → ExportResult`	Export a single article as a standalone HTML file.
`exportArticles(_ stories: [RSSStory]) → ExportResult?`	Batch export multiple articles into a single HTML file with table of contents. Returns `nil` if the array is empty.
`save(_ result: ExportResult, to directory: URL) → URL?`	Write the export result to disk. Returns the file URL on success.
`listArchives(in directory: URL) → [(filename, date, size)]`	List all `.html` archive files in a directory.
`deleteArchive(named:in:) → Bool`	Delete an archive file by name.
`countWords(_ text: String) → Int`	Count words in a text string.
`estimateReadTime(wordCount: Int) → Int`	Estimate reading time in minutes (assumes 200 wpm).

Usage

let exporter = ArticleArchiveExporter(options: .init(theme: .dark))
let result = exporter.exportArticle(story)
if let url = exporter.save(result, to: archiveDir) {
    print("Saved to \(url)")
}
        

FeedHealthMonitor

Monitors feed health by analyzing article publication dates. Classifies feeds as healthy, warning, stale, or dead and generates actionable reports with scores and recommendations.

Types

Type	Description
`FeedHealthStatus`	Enum: `.healthy`, `.warning`, `.stale`, `.dead`. Comparable by severity.
`FeedHealthResult`	Per-feed result with `status`, `score` (0–100), `daysSinceLastArticle`, `averageUpdateInterval`, `issues`, and `recommendations`.
`FeedHealthReport`	Aggregate report with `results`, `overallScore`, `overallStatus`, `statusCounts`, and JSON export via `jsonDict`.
`FeedHealthConfig`	Configures thresholds: `warningDays`, `staleDays`, `deadDays`, `minimumArticleCount`, `maxUpdateIntervalDays`.

Methods

Method	Description
`checkFeed(feedName:feedURL:articleDates:) → FeedHealthResult`	Analyze a single feed's health based on its article publication dates.
`generateReport(feeds:) → FeedHealthReport`	Generate a comprehensive health report for multiple feeds at once.
`detectTrend(articleDates:) → Double?`	Detect publishing frequency trend. Returns a multiplier (>1 = accelerating, <1 = decelerating).

Usage

let monitor = FeedHealthMonitor()
let result = monitor.checkFeed(
    feedName: "Swift Blog",
    feedURL: "https://swift.org/blog/feed.xml",
    articleDates: dates
)
print(result.summary)  // "Swift Blog: healthy (92/100)"
        

Property	Description
`minimumWordLength: Int`	Minimum character length for a word to be considered (default: 3).
`defaultCount: Int`	Default number of keywords to return (default: 5).

Method	Description
`extractKeywords(from text: String, count: Int?) → [String]`	Extract top keywords from raw text.
`extractTags(from story: RSSStory, count: Int?) → [String]`	Extract keyword tags from a story's title and body.
`extractThemes(from stories: [RSSStory], count: Int?) → [String]`	Extract common themes across a collection of stories.

📖 API Reference

RSSParser

Properties

Methods

Usage

RSSParserDelegate

Required Methods

RSSStory

Properties

Initializer

Static Methods

Equality

FeedItem

Properties

Initializer

Static Properties

Usage

NetworkReachability

Static Methods

Usage

ArticleArchiveExporter

Initialization

Types

Methods

Usage

FeedHealthMonitor

Types

Methods

Usage

KeywordExtractor

Properties

Methods

Usage