feat(smartfeed): Implement Smartfeed core: add feed validation, parsing, exporting and comprehensive tests

ts/classes.smartfeed.ts

@@ -1,15 +1,91 @@
-import { Feed } from './smartfeed.classes.feed.js';
-import type { IFeedOptions } from './smartfeed.classes.feed.js';
-import * as plugins from './smartfeed.plugins.js';
+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 {
-  public createFeed(optionsArg: IFeedOptions) {
+  /**
+   * 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 feed from a standardized article object (@tsclass/tsclass).content.IArticle
+   * 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,
@@ -31,8 +107,17 @@ export class Smartfeed {
   }
 
   /**
-   * allows the parsing of a rss feed string
-   * @param rssFeedString
+   * 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();
@@ -41,8 +126,16 @@ export class Smartfeed {
   }
 
   /**
-   * allows the parsing of a feed from urls
-   * @param urlArg
+   * 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();