smartfeed/ts/classes.smartfeed.ts

import { Feed } from './classes.feed.js';
import type { IFeedOptions } from './classes.feed.js';
import { PodcastFeed } from './classes.podcast.js';
import type { IPodcastFeedOptions } from './classes.podcast.js';
import * as plugins from './plugins.js';

/**
 * Main class for creating and parsing various feed formats (RSS, Atom, JSON Feed)
 * @example
 * ```typescript
 * const smartfeed = new Smartfeed();
 * const feed = smartfeed.createFeed({
 *   domain: 'example.com',
 *   title: 'My Blog',
 *   description: 'A blog about technology',
 *   category: 'Technology',
 *   company: 'Example Inc',
 *   companyEmail: 'hello@example.com',
 *   companyDomain: 'https://example.com'
 * });
 * ```
 */
export class Smartfeed {
  /**
   * Creates a new Feed instance with the provided configuration
   * @param optionsArg - Feed configuration options
   * @returns A new Feed instance
   * @throws Error if validation fails
   * @example
   * ```typescript
   * const feed = smartfeed.createFeed({
   *   domain: 'example.com',
   *   title: 'My Blog',
   *   description: 'Latest news and updates',
   *   category: 'Technology',
   *   company: 'Example Inc',
   *   companyEmail: 'hello@example.com',
   *   companyDomain: 'https://example.com'
   * });
   * ```
   */
  public createFeed(optionsArg: IFeedOptions): Feed {
    const feedVersion = new Feed(optionsArg);
    return feedVersion;
  }

  /**
   * Creates a new PodcastFeed instance with iTunes and Podcast namespace support
   * @param optionsArg - Podcast feed configuration options
   * @returns A new PodcastFeed instance
   * @throws Error if validation fails
   * @example
   * ```typescript
   * const podcast = smartfeed.createPodcastFeed({
   *   domain: 'podcast.example.com',
   *   title: 'My Podcast',
   *   description: 'An awesome podcast about tech',
   *   category: 'Technology',
   *   company: 'Podcast Inc',
   *   companyEmail: 'podcast@example.com',
   *   companyDomain: 'https://example.com',
   *   itunesCategory: 'Technology',
   *   itunesAuthor: 'John Doe',
   *   itunesOwner: { name: 'John Doe', email: 'john@example.com' },
   *   itunesImage: 'https://example.com/artwork.jpg',
   *   itunesExplicit: false
   * });
   * ```
   */
  public createPodcastFeed(optionsArg: IPodcastFeedOptions): PodcastFeed {
    const podcastFeed = new PodcastFeed(optionsArg);
    return podcastFeed;
  }

  /**
   * Creates an Atom feed from an array of standardized article objects
   * Uses the @tsclass/tsclass IArticle interface for article format
   * @param optionsArg - Feed configuration options
   * @param articleArray - Array of article objects conforming to @tsclass/tsclass IArticle interface
   * @returns Promise resolving to Atom feed XML string
   * @throws Error if validation fails for feed options or articles
   * @example
   * ```typescript
   * const feedString = await smartfeed.createFeedFromArticleArray(
   *   feedOptions,
   *   articles
   * );
   * ```
   */
  public async createFeedFromArticleArray(
    optionsArg: IFeedOptions,
    articleArray: plugins.tsclass.content.IArticle[],
  ): Promise<string> {
    const feed = this.createFeed(optionsArg);
    for (const article of articleArray) {
      feed.addItem({
        authorName: `${article.author.firstName} ${article.author.surName}`,
        timestamp: article.timestamp,
        imageUrl: article.featuredImageUrl,
        title: article.title,
        url: article.url,
        content: article.content,
      });
    }
    const feedXmlString = feed.exportAtomFeed();
    return feedXmlString;
  }

  /**
   * Parses an RSS or Atom feed from a string
   * @param rssFeedString - The RSS/Atom feed XML string to parse
   * @returns Promise resolving to parsed feed object
   * @throws Error if feed parsing fails
   * @example
   * ```typescript
   * const feedString = '<rss>...</rss>';
   * const parsed = await smartfeed.parseFeedFromString(feedString);
   * console.log(parsed.title);
   * console.log(parsed.items);
   * ```
   */
  public async parseFeedFromString(rssFeedString: string) {
    const parser = new plugins.rssParser();
    const resultingFeed = await parser.parseString(rssFeedString);
    return resultingFeed;
  }

  /**
   * Parses an RSS or Atom feed from a URL
   * @param urlArg - The absolute URL of the RSS/Atom feed
   * @returns Promise resolving to parsed feed object
   * @throws Error if feed fetch or parsing fails
   * @example
   * ```typescript
   * const parsed = await smartfeed.parseFeedFromUrl('https://example.com/feed.xml');
   * console.log(parsed.title);
   * console.log(parsed.items);
   * ```
   */
  public async parseFeedFromUrl(urlArg: string) {
    const parser = new plugins.rssParser();
    const resultingFeed = await parser.parseURL(urlArg);
    return resultingFeed;
  }
}