html2rss 0.33.0 → 0.34.0

data/lib/html2rss/config/auto_source_contract.rb

@@ -4,61 +4,68 @@ require 'dry-validation'
 
 module Html2rss
   class Config
+    # Scraper options are splatted into scraper constructors, so a key no scraper accepts is a
+    # validation error. Key validation applies only when a schema is called directly, so the
+    # auto-source contract keeps +scraper+ an open hash and {Validator} applies this one to it.
+    # The raw values reach the scrapers, so this schema checks types without coercing them.
+    AutoSourceScraperContract = Dry::Schema.JSON do # rubocop:disable Metrics/BlockLength
+      config.validate_keys = true
+
+      optional(:native_feed).hash do
+        optional(:enabled).filled(:bool)
+      end
+      optional(:wordpress_api).hash do
+        optional(:enabled).filled(:bool)
+      end
+      optional(:sitemap).hash do
+        optional(:enabled).filled(:bool)
+        optional(:min_priority).filled { int? | float? }
+        optional(:max_age_days).filled(:integer, gt?: 0)
+      end
+      optional(:schema).hash do
+        optional(:enabled).filled(:bool)
+      end
+      optional(:microdata).hash do
+        optional(:enabled).filled(:bool)
+      end
+      optional(:microformats2).hash do
+        optional(:enabled).filled(:bool)
+      end
+      optional(:json_state).hash do
+        optional(:enabled).filled(:bool)
+      end
+      optional(:json_document).hash do
+        optional(:enabled).filled(:bool)
+      end
+      optional(:xhr_articles).hash do
+        optional(:enabled).filled(:bool)
+      end
+      optional(:meta_oembed).hash do
+        optional(:enabled).filled(:bool)
+      end
+      optional(:semantic_html).hash do
+        optional(:enabled).filled(:bool)
+      end
+      optional(:html).hash do
+        optional(:enabled).filled(:bool)
+        optional(:minimum_selector_frequency).filled(:integer, gt?: 0)
+        optional(:use_top_selectors).filled(:integer, gt?: 0)
+      end
+    end
+
     # Runtime source of truth for validating auto-source config values.
-    AutoSourceContract = Dry::Schema.Params do # rubocop:disable Metrics/BlockLength
+    AutoSourceContract = Dry::Schema.Params do
       optional(:limit).filled(:integer, gt?: 0)
       optional(:entry_resolution).hash do
         optional(:enabled).filled(:bool)
         optional(:max_probes).filled(:integer, gt?: 0)
       end
 
-      optional(:scraper).hash do # rubocop:disable Metrics/BlockLength
-        optional(:native_feed).hash do
-          optional(:enabled).filled(:bool)
-        end
-        optional(:wordpress_api).hash do
-          optional(:enabled).filled(:bool)
-        end
-        optional(:sitemap).hash do
-          optional(:enabled).filled(:bool)
-          optional(:min_priority).filled(:float)
-          optional(:max_age_days).filled(:integer, gt?: 0)
-        end
-        optional(:schema).hash do
-          optional(:enabled).filled(:bool)
-        end
-        optional(:microdata).hash do
-          optional(:enabled).filled(:bool)
-        end
-        optional(:microformats2).hash do
-          optional(:enabled).filled(:bool)
-        end
-        optional(:json_state).hash do
-          optional(:enabled).filled(:bool)
-        end
-        optional(:json_document).hash do
-          optional(:enabled).filled(:bool)
-        end
-        optional(:xhr_articles).hash do
-          optional(:enabled).filled(:bool)
-        end
-        optional(:meta_oembed).hash do
-          optional(:enabled).filled(:bool)
-        end
-        optional(:semantic_html).hash do
-          optional(:enabled).filled(:bool)
-          optional(:fallback_anchorless).filled(:bool)
-        end
-        optional(:html).hash do
-          optional(:enabled).filled(:bool)
-          optional(:minimum_selector_frequency).filled(:integer, gt?: 0)
-          optional(:use_top_selectors).filled(:integer, gt?: 0)
-          optional(:fallback_anchorless).filled(:bool)
-        end
-      end
+      optional(:scraper).hash
 
       optional(:cleanup).hash do
         optional(:keep_different_domain).filled(:bool)
+        optional(:keep_sponsored).filled(:bool)
       end
     end
   end

data/lib/html2rss/config/issue_mapper.rb

@@ -6,6 +6,9 @@ module Html2rss
     # Maps internal Dry::Validation messages to {ValidationIssue} (predicate → code).
     # Not a public API — Dry stays inside Validator / this mapper.
     module IssueMapper
+      # Raised when the schema yields a Dry predicate this mapper has no code for (a mapping-table gap).
+      class InvalidError < Html2rss::ContractError; end
+
       # Dry schema predicates → closed {ValidationIssue::CODES}.
       PREDICATE_CODES = {
         key?: :missing_key,
@@ -65,7 +68,7 @@ module Html2rss
           return :invalid_value if predicate.nil?
 
           PREDICATE_CODES.fetch(predicate) do
-            raise ArgumentError, "unmapped Dry validation predicate: #{predicate.inspect}"
+            raise InvalidError, "unmapped Dry validation predicate: #{predicate.inspect}"
           end
         end
 

data/lib/html2rss/config/request_controls.rb

@@ -50,15 +50,18 @@ module Html2rss
       # @param strategy [Symbol, nil]
       # @param max_redirects [Integer, nil]
       # @param max_requests [Integer, nil]
+      # @param total_timeout_seconds [Integer, nil] wall-clock bound for the whole request chain
       # @return [RequestControls]
-      def self.from_shortcut(strategy:, max_redirects: nil, max_requests: nil)
+      def self.from_shortcut(strategy:, max_redirects: nil, max_requests: nil, total_timeout_seconds: nil)
         strategy = Option.strategy(strategy) unless strategy.nil?
         check_budgets!(max_redirects, max_requests)
+        Option.integer(:total_timeout_seconds, total_timeout_seconds, min: 1, optional: true)
         keys = []
         keys << :strategy unless strategy.nil? || strategy == Config.default_strategy_name
         keys << :max_redirects unless max_redirects.nil?
         keys << :max_requests unless max_requests.nil?
-        new(strategy:, max_redirects:, max_requests:, explicit_keys: keys)
+        keys << :total_timeout_seconds unless total_timeout_seconds.nil?
+        new(strategy:, max_redirects:, max_requests:, total_timeout_seconds:, explicit_keys: keys)
       end
 
       ##
@@ -170,7 +173,7 @@ module Html2rss
         return config[:request] = {} if request_config.nil?
         return if request_config.is_a?(Hash)
 
-        raise ArgumentError, 'request config must be a hash'
+        raise InvalidOption, 'request config must be a hash'
       end
     end
   end

data/lib/html2rss/config/schema.rb

@@ -105,6 +105,17 @@ module Html2rss
           request[:botasaurus] = exported
         end
 
+        # Scraper options are splatted into scraper constructors, so the scraper map and each
+        # scraper object reject keys the contract does not name.
+        def auto_source_schema
+          schema = Html2rss::Config::AutoSourceContract.json_schema(loose: true)
+          scraper = Html2rss::Config::AutoSourceScraperContract.json_schema(loose: true).except(:$schema)
+          scraper[:additionalProperties] = false
+          scraper.fetch(:properties).each_value { |options| options[:additionalProperties] = false }
+          schema.fetch(:properties)[:scraper] = scraper
+          schema.merge(default: HashUtil.deep_stringify_keys(Html2rss::AutoSource::DEFAULT_CONFIG))
+        end
+
         # @return [Hash{Symbol => Hash}] catalog under $defs.post_processors / $defs.extractors
         def registry_catalog_defs
           {
@@ -127,8 +138,9 @@ module Html2rss
             default: Html2rss::Selectors::DEFAULT_ITEMS_SELECTOR
           )
           items_schema[:properties][:enhance] = items_schema.fetch(:properties).fetch(:enhance).merge(
-            description: 'List-card enrichment: run Html::ArticleExtractor on each matched item node ' \
-                         'to fill missing fields from the card HTML.'
+            description: 'Fills missing title, link, description, date, image and categories from each ' \
+                         "item's own markup via Html::ArticleExtractor. Explicit selectors win; no extra " \
+                         'requests are made.'
           )
           items_schema[:properties][:pagination] = {
             description: 'Pagination configuration or maximum page count integer.',
@@ -175,9 +187,7 @@ module Html2rss
               description: 'Collection of stylesheets to attach to the RSS feed.',
               items: Html2rss::Config::Validator::StylesheetConfig.json_schema(loose: true)
             },
-            auto_source: Html2rss::Config::AutoSourceContract.json_schema(loose: true).merge(
-              default: HashUtil.deep_stringify_keys(Html2rss::AutoSource::DEFAULT_CONFIG)
-            ),
+            auto_source: auto_source_schema,
             selectors: {
               type: 'object',
               description: 'Selectors used to extract article attributes.',

data/lib/html2rss/config/selectors_validator.rb

@@ -142,7 +142,7 @@ module Html2rss
           end
         end
 
-        # Same compile as Gsub#call. ArgumentError is the bound; Gsub maps
+        # Same compile as Gsub#call. InvalidOption is the bound; Gsub maps
         # parser errors onto that path so admit and execute still share it.
         #
         # @param klass [Class]
@@ -156,7 +156,7 @@ module Html2rss
 
           Selectors::PostProcessors::Gsub.compiled_pattern(pattern)
           nil
-        rescue ArgumentError => error
+        rescue InvalidOption => error
           error.message
         end
       end

data/lib/html2rss/config/validation_issue.rb

@@ -10,6 +10,9 @@ module Html2rss
     # +path+ is JSON-pointer-friendly segments. +code+ is closed ({CODES}).
     # +expected+ / +actual+ are JSON-ish or +nil+ (never invented).
     class ValidationIssue
+      # Raised when an issue is built with a code outside {CODES}.
+      class InvalidError < Html2rss::ContractError; end
+
       # Closed set of issue codes (mapper owns Dry predicate → code).
       CODES = Set[
         :missing_key,
@@ -27,7 +30,7 @@ module Html2rss
       # @param expected [Hash, String, Numeric, true, false, nil]
       # @param actual [Hash, String, Numeric, true, false, nil]
       def initialize(path:, code:, message:, expected: nil, actual: nil)
-        raise ArgumentError, "unknown ValidationIssue code: #{code.inspect}" unless CODES.include?(code)
+        raise InvalidError, "unknown ValidationIssue code: #{code.inspect}" unless CODES.include?(code)
 
         super(
           path: Array(path).freeze,

data/lib/html2rss/config/validator.rb

@@ -153,6 +153,17 @@ module Html2rss
         end
       end
 
+      rule(auto_source: :scraper) do
+        next unless value
+
+        result = Config::AutoSourceScraperContract.call(value)
+        next if result.success?
+
+        result.errors.each do |error|
+          key([:auto_source, :scraper, *error.path]).failure(error.text)
+        end
+      end
+
       # URL validation delegated to Url class
       rule(:channel) do
         if (url_string = values.dig(:channel, :url)) && !url_string.empty?

data/lib/html2rss/config.rb

@@ -11,7 +11,7 @@ module Html2rss
   #
   # Configuration is validated during initialization.
   class Config # rubocop:disable Metrics/ClassLength
-    # Raised when a configuration hash fails runtime validation.
+    # Raised when a configuration cannot be loaded (YAML shape, file, feed name) or fails runtime validation.
     class InvalidConfig < Html2rss::Error; end
 
     class << self
@@ -25,7 +25,7 @@ module Html2rss
       # @return [Array(Hash, Html2rss::Config::ValidationReport)]
       def resolve_and_validate(config_input, feed_name: nil, params: {})
         raw = resolve_raw_hash(config_input, feed_name)
-      rescue Psych::Exception, ArgumentError => error
+      rescue InvalidConfig => error
         [{}, IssueMapper.parse_failure(error.message)]
       else
         working = HashUtil.deep_dup(raw)
@@ -66,14 +66,16 @@ module Html2rss
       #
       # @param string [String] YAML document
       # @return [Hash{Symbol => Object}] configuration hash
-      # @raise [ArgumentError] if +string+ is not a String or does not deserialize to a Hash
+      # @raise [InvalidConfig] if +string+ is not a String or does not deserialize to a Hash
       def from_yaml(string)
-        raise ArgumentError, 'YAML must be a String' unless string.is_a?(String)
+        raise InvalidConfig, 'YAML must be a String' unless string.is_a?(String)
 
         parsed = YAML.safe_load(string)
-        raise ArgumentError, 'YAML must deserialize to a Hash' unless parsed.is_a?(Hash)
+        raise InvalidConfig, 'YAML must deserialize to a Hash' unless parsed.is_a?(Hash)
 
-        HashUtil.deep_symbolize_keys(parsed, context: 'config')
+        symbolize_config(parsed)
+      rescue Psych::Exception => error
+        raise InvalidConfig, "YAML could not be parsed: #{error.message}"
       end
 
       ##
@@ -85,25 +87,16 @@ module Html2rss
       # @param feed_name [String, nil] the feed name when using multiple feeds.
       # @param multiple_feeds_key [Symbol] the key under which multiple feeds are defined.
       # @return [Hash{Symbol => Object}] the configuration hash.
-      # @raise [ArgumentError] if the file doesn't exist or feed is not found.
-      # rubocop:disable-next Metrics/MethodLength
+      # @raise [InvalidConfig] if the file doesn't exist or feed is not found.
       def load_yaml(file, feed_name = nil, multiple_feeds_key: MultipleFeedsConfig::CONFIG_KEY_FEEDS)
-        raise ArgumentError, "File '#{file}' does not exist" unless File.exist?(file)
-        raise ArgumentError, "`#{multiple_feeds_key}` is a reserved feed name" if feed_name == multiple_feeds_key
+        raise InvalidConfig, "File '#{file}' does not exist" unless File.exist?(file)
+        raise InvalidConfig, "`#{multiple_feeds_key}` is a reserved feed name" if feed_name == multiple_feeds_key
 
-        yaml = YAML.safe_load_file(file, symbolize_names: true)
+        yaml = read_yaml_mapping(file)
 
         return yaml unless yaml.key?(multiple_feeds_key)
 
-        unless feed_name
-          available_feeds = yaml.fetch(multiple_feeds_key).keys.join(', ')
-          raise ArgumentError,
-                "Feed name is required under `#{multiple_feeds_key}`. Available feeds: #{available_feeds}"
-        end
-
-        config = yaml.dig(multiple_feeds_key, feed_name.to_sym)
-        raise ArgumentError, "Feed '#{feed_name}' not found under `#{multiple_feeds_key}` key." unless config
-
+        config = select_feed(file, feed_name, yaml.fetch(multiple_feeds_key), multiple_feeds_key)
         MultipleFeedsConfig.to_single_feed(config, yaml, multiple_feeds_key:)
       end
 
@@ -126,17 +119,15 @@ module Html2rss
       # @param request_controls [Html2rss::Config::RequestControls, nil] explicit request controls to write
       # @param limit [Integer, nil] max articles to keep in the auto-sourced feed
       # @param keep_different_domain [Boolean, nil] when set, overrides cleanup.keep_different_domain
+      # @param keep_sponsored [Boolean, nil] when set, overrides cleanup.keep_sponsored
       # @return [Hash{Symbol => Object}] feed config hash ready for {from_hash}
-      # rubocop:disable-next Metrics/MethodLength -- keep_different_domain override stays co-located
+      # rubocop:disable-next Metrics/MethodLength, Metrics/ParameterLists -- cleanup overrides stay co-located
       def auto_source_config(url:, items_selector: nil, request_controls: nil, limit: nil,
-                             keep_different_domain: nil)
+                             keep_different_domain: nil, keep_sponsored: nil)
         auto_source = AutoSource::DEFAULT_CONFIG
         auto_source = auto_source.merge(limit: Option.integer(:limit, limit, min: 1)) unless limit.nil?
-        unless keep_different_domain.nil?
-          auto_source = auto_source.merge(
-            cleanup: auto_source[:cleanup].merge(keep_different_domain:)
-          )
-        end
+        cleanup = { keep_different_domain:, keep_sponsored: }.compact
+        auto_source = auto_source.merge(cleanup: auto_source[:cleanup].merge(cleanup)) unless cleanup.empty?
 
         config = {
           channel: default_config[:channel].merge(url:),
@@ -228,6 +219,41 @@ module Html2rss
         end
       end
       private :resolve_raw_hash
+
+      def read_yaml_mapping(file)
+        yaml = YAML.safe_load_file(file)
+        return symbolize_config(yaml) if yaml.is_a?(Hash)
+
+        raise InvalidConfig, "File '#{file}' must contain a YAML mapping (a Hash)"
+      rescue Psych::Exception => error
+        raise InvalidConfig, "File '#{file}' could not be parsed: #{error.message}"
+      end
+      private :read_yaml_mapping
+
+      # @return [Hash{Symbol => Object}] the named feed's config from the +feeds+ mapping
+      def select_feed(file, feed_name, feeds, key)
+        unless feeds.is_a?(Hash)
+          raise InvalidConfig, "File '#{file}': `#{key}` must be a mapping of feed names to configs"
+        end
+        unless feed_name
+          raise InvalidConfig, "Feed name is required under `#{key}`. Available feeds: #{feeds.keys.join(', ')}"
+        end
+
+        config = feeds[feed_name.to_sym]
+        raise InvalidConfig, "Feed '#{feed_name}' not found under `#{key}` key." unless config
+        raise InvalidConfig, "File '#{file}': feed '#{feed_name}' must be a mapping" unless config.is_a?(Hash)
+
+        config
+      end
+      private :select_feed
+
+      # Loaded config keys that cannot be symbolized (non-string, non-symbol) are a config-load failure.
+      def symbolize_config(parsed)
+        HashUtil.deep_symbolize_keys(parsed, context: 'config')
+      rescue InvalidOption => error
+        raise InvalidConfig, error.message
+      end
+      private :symbolize_config
     end
 
     ##

data/lib/html2rss/contract_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Html2rss
+  ##
+  # Base for programmer errors: a value object built from wrong parts (each owner's +InvalidError+) or a
+  # component breaking its contract ({AutoSource::ScraperContractError}). It is an {Error}, but no
+  # operational rescue may swallow it: every broad +rescue Html2rss::Error+ in +lib/+ re-raises it first.
+  class ContractError < Error; end
+end

data/lib/html2rss/defaults.rb

@@ -55,9 +55,9 @@ module Html2rss
     #
     # @param logger [Logger]
     # @return [Logger] the logger
-    # @raise [ArgumentError] if logger is not a Logger
+    # @raise [InvalidOption] if logger is not a Logger
     def logger=(logger)
-      raise ArgumentError, 'logger must be a Logger' unless logger.is_a?(Logger)
+      raise InvalidOption, 'logger must be a Logger' unless logger.is_a?(Logger)
 
       @logger = logger
       @logger.level = @log_level
@@ -69,7 +69,7 @@ module Html2rss
     #
     # @param level [Symbol, String, Integer] the new log level
     # @return [Integer] the normalized log level
-    # @raise [ArgumentError] if the log level is invalid
+    # @raise [InvalidOption] if the log level is invalid
     def log_level=(level)
       @log_level = normalize_log_level(level)
       @logger.level = @log_level
@@ -80,13 +80,13 @@ module Html2rss
     #
     # @param formatter [Proc, Logger::Formatter, nil] the new logger formatter
     # @return [Proc, Logger::Formatter, nil] the new logger formatter
-    # @raise [ArgumentError] if formatter is not a Proc, Logger::Formatter, or nil
+    # @raise [InvalidOption] if formatter is not a Proc, Logger::Formatter, or nil
     def logger_formatter=(formatter)
       @logger_formatter = case formatter
                           when nil, Proc, Logger::Formatter
                             formatter
                           else
-                            raise ArgumentError, 'formatter must be a Proc, Logger::Formatter, or nil'
+                            raise InvalidOption, 'formatter must be a Proc, Logger::Formatter, or nil'
                           end
       @logger.formatter = @logger_formatter
     end
@@ -96,14 +96,14 @@ module Html2rss
     #
     # @param headers [Hash, Proc, nil] the HTTP request headers to globally apply
     # @return [Hash, Proc, nil] the assigned headers
-    # @raise [ArgumentError] if headers is not a Hash, Proc, or nil
+    # @raise [InvalidOption] if headers is not a Hash, Proc, or nil
     def headers=(headers)
       @headers = case headers
                  when nil then nil
                  when Hash then headers.dup.freeze
                  when Proc then headers
                  else
-                   raise ArgumentError, 'headers must be a Hash or Proc'
+                   raise InvalidOption, 'headers must be a Hash or Proc'
                  end
     end
 
@@ -124,18 +124,9 @@ module Html2rss
     #
     # @param ttl [Integer, String, nil] the minimum TTL
     # @return [Integer, nil] the normalized minimum TTL
-    # @raise [ArgumentError] if ttl is not a positive integer
+    # @raise [InvalidOption] if ttl is not a positive integer
     def min_ttl=(ttl)
-      if ttl.nil?
-        @min_ttl = nil
-      else
-        val = Integer(ttl)
-        raise ArgumentError unless val.positive?
-
-        @min_ttl = val
-      end
-    rescue ArgumentError, TypeError
-      raise ArgumentError, "min_ttl must be a positive integer, got #{ttl.inspect}"
+      @min_ttl = (positive_ttl(ttl) unless ttl.nil?)
     end
 
     ##
@@ -143,10 +134,10 @@ module Html2rss
     #
     # @param stylesheets [Array<Hash>] the XML stylesheet processing instructions to include in the generated feed
     # @return [Array<Hash>] the assigned stylesheets
-    # @raise [ArgumentError] if stylesheets is not an Array of hashes
+    # @raise [InvalidOption] if stylesheets is not an Array of hashes
     def stylesheets=(stylesheets)
-      raise ArgumentError, 'stylesheets must be an Array' unless stylesheets.is_a?(Array)
-      raise ArgumentError, 'stylesheets must be an Array of Hashes' unless stylesheets.all?(Hash)
+      raise InvalidOption, 'stylesheets must be an Array' unless stylesheets.is_a?(Array)
+      raise InvalidOption, 'stylesheets must be an Array of Hashes' unless stylesheets.all?(Hash)
 
       @stylesheets = stylesheets.map { |h| h.dup.freeze }.freeze
     end
@@ -166,13 +157,20 @@ module Html2rss
 
     private
 
+    def positive_ttl(ttl)
+      val = Integer(ttl, exception: false)
+      return val if val&.positive?
+
+      raise InvalidOption, "min_ttl must be a positive integer, got #{ttl.inspect}"
+    end
+
     def normalize_log_level(level)
       if level.is_a?(Integer)
-        raise ArgumentError, "invalid log level: #{level}" unless LOG_LEVELS.value?(level)
+        raise InvalidOption, "invalid log level: #{level}" unless LOG_LEVELS.value?(level)
 
         level
       else
-        LOG_LEVELS.fetch(level.to_s.downcase.to_sym) { raise ArgumentError, "invalid log level: #{level}" }
+        LOG_LEVELS.fetch(level.to_s.downcase.to_sym) { raise InvalidOption, "invalid log level: #{level}" }
       end
     end
   end

data/lib/html2rss/doctor/botasaurus.rb

@@ -68,12 +68,14 @@ module Html2rss
       # @param base_url [String]
       # @return [Hash{Symbol => Object}]
       def self.health_check(base_url)
-        endpoint = "#{Url.for_channel(base_url).to_s.chomp('/')}/health"
-        response = health_session.get(endpoint)
+        response = health_session.get("#{Url.for_channel(base_url).to_s.chomp('/')}/health")
         raise response.error if response.is_a?(HTTPX::ErrorResponse)
 
         body = JSON.parse(response.body.to_s)
-        { ok: response.status == 200, status: response.status, version: body['version'] }
+        status = response.status
+        { ok: status == 200, status:, version: body['version'] }
+      rescue Html2rss::ContractError
+        raise
       rescue StandardError => error
         { ok: false, error: "#{error.class}: #{error.message}" }
       end
@@ -94,6 +96,8 @@ module Html2rss
           status: wire[:status],
           articles_count: wire[:articles_count]
         }
+      rescue Html2rss::ContractError
+        raise
       rescue Html2rss::Error => error
         { ok: false, error: "#{error.class}: #{error.message}" }
       end

data/lib/html2rss/error.rb

@@ -39,6 +39,16 @@ module Html2rss
     # @return [Hash{String => Object}, nil] allowlisted upstream transport telemetry when attached
     attr_accessor :transport_meta
 
+    ##
+    # Stable failure classification, overridden per error class.
+    #
+    # @return [Symbol] one of +:timeout+, +:blocked+, +:connection+, +:invalid_url+, +:budget+, +:other+
+    def kind = :other
+
+    ##
+    # @return [Boolean] whether repeating the same request may succeed (derived from {#kind})
+    def retryable? = ErrorKind[kind].retryable?
+
     # @return [String, nil] scrape-api timeout stage when known (overridden by RequestTimedOut)
     def timeout_phase; end
 

data/lib/html2rss/error_kind.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Html2rss
+  ErrorKind = Data.define(:name, :retryable)
+
+  ##
+  # Closed classification of {Html2rss::Error} failures, so consumers branch on a stable
+  # symbol instead of exception class names. Read it through {Html2rss::Error#kind}.
+  class ErrorKind
+    # Frozen name → instance table. Only transient transport failures are retryable.
+    ALL = {
+      timeout: true,
+      blocked: false,
+      connection: true,
+      invalid_url: false,
+      budget: false,
+      other: false
+    }.to_h { |name, retryable| [name, new(name:, retryable:)] }.freeze
+    private_class_method :new
+
+    ##
+    # @param name [Symbol, String] one of +ALL.keys+
+    # @return [ErrorKind]
+    # @raise [InvalidOption] when the name is not a known kind
+    def self.[](name) = ALL.fetch(name.to_sym) { raise InvalidOption, "unknown error kind: #{name.inspect}" }
+
+    ##
+    # @return [Boolean] whether repeating the same request may succeed
+    def retryable? = retryable
+
+    ##
+    # @return [Symbol]
+    def to_sym = name
+
+    ##
+    # @return [String]
+    def to_s = name.to_s
+  end
+end

data/lib/html2rss/feed_builder/item_presentation.rb

@@ -5,11 +5,15 @@ module Html2rss
     ##
     # Presentation rules for rendering an {Html2rss::Article} into feed wire formats.
     #
-    # Owns description enrichment ({Html::Rendering::DescriptionBuilder}) and RSS
-    # non-image enclosure selection. {Article} keeps raw extracted fields only.
+    # Owns description enrichment ({Html::Rendering::DescriptionBuilder}), RSS enclosure
+    # choice and the media-feed rule. {Article} keeps raw extracted fields only; media-file
+    # facts live on {Article::Enclosure}.
     module ItemPresentation
       class << self
         ##
+        # The item body: sanitized description text after at most one media element, the RSS enclosure
+        # ({.rss_enclosure_for}) when it is audio or video, else the item image ({Html::Rendering::DescriptionBuilder}).
+        #
         # @param article [Html2rss::Article]
         # @return [String, nil] sanitized description HTML/text for feed item bodies
         def description_for(article)
@@ -17,24 +21,33 @@ module Html2rss
             base: article.description,
             title: article.title,
             url: article.url,
-            enclosures: article.enclosures,
+            enclosure: rss_enclosure_for(article),
             image: article.image
           ).call
         end
 
         ##
-        # First non-image enclosure for RSS +enclosure+ (images stay on description / JSON Feed).
+        # The one RSS +enclosure+ of an item: its first audio or video file, else its first downloadable
+        # document or archive ({Article::Enclosure#document?}: PDF, ZIP). Images stay on the description /
+        # JSON Feed; stream playlists, Flash players and watch or player pages ({Article::Enclosure#player_page?})
+        # are never one.
         #
         # @param article [Html2rss::Article]
         # @return [Html2rss::Article::Enclosure, nil]
         def rss_enclosure_for(article)
-          article.enclosures.find { |enc| !image_mime_type?(enc.type) }
+          enclosures = article.enclosures
+          enclosures.find(&:media?) || enclosures.find(&:document?)
         end
 
-        private
-
-        def image_mime_type?(type)
-          type.to_s.downcase.start_with?('image/')
+        ##
+        # A media feed (podcast) is one where more than half of the items carry an audio or video
+        # RSS enclosure; only such a feed gets podcast (+itunes:+) tags.
+        #
+        # @param articles [Array<Html2rss::Article>]
+        # @return [Boolean]
+        def media_feed?(articles)
+          media_items = articles.count { |article| article.enclosures.any?(&:media?) }
+          media_items * 2 > articles.size
         end
       end
     end