brand_logo 1.0.0

data/lib/brand_logo/strategies/duckduckgo_strategy.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+# typed: strict
+
+require 'sorbet-runtime'
+
+module BrandLogo
+  module Strategies
+    # Fetches brand logos from DuckDuckGo's public icon service.
+    # Used as a last-resort fallback when scraping finds nothing.
+    class DuckduckgoStrategy < BaseStrategy
+      extend T::Sig
+
+      DUCKDUCKGO_URL = T.let('https://icons.duckduckgo.com/ip3/%s.ico', String)
+
+      sig do
+        params(
+          config: Config,
+          http_client: HttpClient,
+          image_analyzer: ImageAnalyzer
+        ).void
+      end
+      def initialize(config:, http_client:, image_analyzer:)
+        super(config: config)
+        @http_client    = T.let(http_client, HttpClient)
+        @image_analyzer = T.let(image_analyzer, ImageAnalyzer)
+      end
+
+      sig { override.params(domain: String).returns(T::Array[Icon]) }
+      def fetch_all(domain)
+        url = format(DUCKDUCKGO_URL, domain)
+        return [] unless @http_client.head_success?(url)
+
+        icon = Icon.new(
+          url: url,
+          dimensions: @image_analyzer.dimensions(url),
+          format: 'ico'
+        )
+        [icon]
+      rescue StandardError => e
+        BrandLogo::Logging.logger.error("DuckduckgoStrategy error for #{domain}: #{e.message}")
+        []
+      end
+    end
+  end
+end

data/lib/brand_logo/strategies/manifest_strategy.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+# typed: strict
+
+require 'sorbet-runtime'
+require 'json'
+
+module BrandLogo
+  module Strategies
+    # Fetches icons from the Web App Manifest (PWA manifest).
+    # Modern progressive web apps store high-resolution icons (192x192, 512x512)
+    # in a manifest.json or .webmanifest file linked from the HTML.
+    #
+    # Flow:
+    #   1. Fetch HTML → find <link rel="manifest" href="...">
+    #   2. Fetch manifest JSON
+    #   3. Parse icons[] array → build Icons
+    class ManifestStrategy < BaseStrategy
+      extend T::Sig
+
+      MIME_TO_FORMAT = T.let({
+        'image/png' => 'png',
+        'image/svg+xml' => 'svg',
+        'image/jpeg' => 'jpg',
+        'image/webp' => 'webp',
+        'image/gif' => 'gif'
+      }.freeze, T::Hash[String, String])
+
+      sig do
+        params(
+          config: Config,
+          http_client: HttpClient,
+          html_parser: HtmlParser,
+          image_analyzer: ImageAnalyzer
+        ).void
+      end
+      def initialize(config:, http_client:, html_parser:, image_analyzer:)
+        super(config: config)
+        @http_client    = T.let(http_client, HttpClient)
+        @html_parser    = T.let(html_parser, HtmlParser)
+        @image_analyzer = T.let(image_analyzer, ImageAnalyzer)
+      end
+
+      sig { override.params(domain: String).returns(T::Array[Icon]) }
+      def fetch_all(domain)
+        manifest_url = find_manifest_url(domain)
+        return [] unless manifest_url
+
+        parse_manifest_icons(manifest_url)
+      rescue StandardError => e
+        BrandLogo::Logging.logger.error("ManifestStrategy error for #{domain}: #{e.message}")
+        []
+      end
+
+      private
+
+      # Finds the manifest URL from the HTML <link rel="manifest"> tag.
+      sig { params(domain: String).returns(T.nilable(String)) }
+      def find_manifest_url(domain)
+        html = fetch_html(domain)
+        return nil unless html
+
+        doc  = @html_parser.parse(html)
+        node = doc.at('link[rel="manifest"]')
+        return nil unless node
+
+        href = node['href']
+        return nil unless href
+
+        Scraping::UrlNormalizer.new("https://#{domain}").normalize(href)
+      end
+
+      sig { params(domain: String).returns(T.nilable(String)) }
+      def fetch_html(domain)
+        @http_client.get_body("https://#{domain}") ||
+          @http_client.get_body("https://www.#{domain}")
+      end
+
+      # Downloads and parses the manifest JSON, returning icons.
+      sig { params(manifest_url: String).returns(T::Array[Icon]) }
+      def parse_manifest_icons(manifest_url)
+        body = @http_client.get_body(manifest_url)
+        return [] unless body
+
+        data = JSON.parse(body)
+        icons_data = data['icons']
+        return [] unless icons_data.is_a?(Array)
+
+        url_normalizer = Scraping::UrlNormalizer.new(manifest_url)
+
+        icons_data.filter_map { |entry| build_icon_from_entry(entry, url_normalizer) }
+      rescue JSON::ParserError => e
+        BrandLogo::Logging.logger.warn("ManifestStrategy: invalid JSON at #{manifest_url}: #{e.message}")
+        []
+      end
+
+      sig { params(entry: T.untyped, url_normalizer: Scraping::UrlNormalizer).returns(T.nilable(Icon)) }
+      def build_icon_from_entry(entry, url_normalizer)
+        return nil unless entry.is_a?(Hash)
+
+        src = entry['src']
+        return nil unless src.is_a?(String) && !src.empty?
+
+        url        = url_normalizer.normalize(src)
+        dimensions = parse_sizes(entry['sizes'])
+        format     = format_from_entry(entry, url)
+
+        BrandLogo::Logging.logger.debug("ManifestStrategy found icon: #{url} #{dimensions}")
+        Icon.new(url: url, dimensions: dimensions, format: format)
+      end
+
+      # Parses a `sizes` entry like "192x192" or "any".
+      sig { params(sizes: T.untyped).returns(T::Hash[Symbol, T.nilable(Integer)]) }
+      def parse_sizes(sizes)
+        return { width: nil, height: nil } unless sizes.is_a?(String)
+
+        parts = sizes.downcase.split('x')
+        return { width: nil, height: nil } unless parts.length == 2
+
+        width, height = parts.map(&:to_i)
+        return { width: nil, height: nil } unless width.positive? && height.positive?
+
+        { width: width, height: height }
+      end
+
+      sig { params(entry: T.untyped, url: String).returns(String) }
+      def format_from_entry(entry, url)
+        mime = entry['type']
+        return MIME_TO_FORMAT[mime] if mime.is_a?(String) && MIME_TO_FORMAT.key?(mime)
+
+        ext = File.extname(URI.parse(url).path).delete('.').downcase
+        ext.empty? ? 'png' : ext
+      rescue URI::Error
+        'png'
+      end
+    end
+  end
+end

data/lib/brand_logo/strategies/meta_tag_strategy.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+# typed: strict
+
+require 'sorbet-runtime'
+
+module BrandLogo
+  module Strategies
+    # Fetches icons from Open Graph and Twitter Card meta tags.
+    # These tags often contain high-resolution images (e.g. 1200x630 og:image),
+    # making them a useful source when `max_dimensions` is not constrained.
+    #
+    # Tried after ScrapingStrategy (which handles dedicated favicon links),
+    # before the DuckDuckGo last-resort fallback.
+    class MetaTagStrategy < BaseStrategy
+      extend T::Sig
+
+      META_SELECTORS = T.let([
+        'meta[property="og:image"]',
+        'meta[name="twitter:image"]',
+        'meta[name="twitter:image:src"]'
+      ].freeze, T::Array[String])
+
+      MIME_TO_FORMAT = T.let({
+        'image/png' => 'png',
+        'image/svg+xml' => 'svg',
+        'image/jpeg' => 'jpg',
+        'image/webp' => 'webp'
+      }.freeze, T::Hash[String, String])
+
+      sig do
+        params(
+          config: Config,
+          http_client: HttpClient,
+          html_parser: HtmlParser,
+          image_analyzer: ImageAnalyzer
+        ).void
+      end
+      def initialize(config:, http_client:, html_parser:, image_analyzer:)
+        super(config: config)
+        @http_client    = T.let(http_client, HttpClient)
+        @html_parser    = T.let(html_parser, HtmlParser)
+        @image_analyzer = T.let(image_analyzer, ImageAnalyzer)
+      end
+
+      sig { override.params(domain: String).returns(T::Array[Icon]) }
+      def fetch_all(domain)
+        html, base_url = fetch_html_with_base_url(domain)
+        return [] unless html
+
+        doc             = @html_parser.parse(html)
+        url_normalizer  = Scraping::UrlNormalizer.new(base_url)
+
+        META_SELECTORS.filter_map { |selector| build_icon_from_selector(doc, selector, url_normalizer) }
+      rescue StandardError => e
+        BrandLogo::Logging.logger.error("MetaTagStrategy error for #{domain}: #{e.message}")
+        []
+      end
+
+      private
+
+      sig { params(doc: ParsedDocument, selector: String, url_normalizer: Scraping::UrlNormalizer).returns(T.nilable(Icon)) }
+      def build_icon_from_selector(doc, selector, url_normalizer)
+        node = doc.at(selector)
+        return nil unless node
+
+        content = node['content']
+        return nil unless content && !content.strip.empty?
+
+        url        = url_normalizer.normalize(content.strip)
+        dimensions = @image_analyzer.dimensions(url)
+        format     = extract_format_from_url(url)
+
+        BrandLogo::Logging.logger.debug("MetaTagStrategy found: #{url} (#{selector})")
+        Icon.new(url: url, dimensions: dimensions, format: format)
+      end
+
+      sig { params(domain: String).returns(T.nilable([String, String])) }
+      def fetch_html_with_base_url(domain)
+        ["https://#{domain}", "https://www.#{domain}"].each do |url|
+          body = @http_client.get_body(url)
+          return [body, url] if body
+        end
+        nil
+      end
+
+      sig { params(url: String).returns(String) }
+      def extract_format_from_url(url)
+        ext = File.extname(URI.parse(url).path).delete('.').downcase
+        ext.empty? ? 'unknown' : ext
+      rescue URI::Error
+        'unknown'
+      end
+    end
+  end
+end

data/lib/brand_logo/strategies/scraping/default_favicon_checker.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+# typed: strict
+
+require 'sorbet-runtime'
+
+module BrandLogo
+  module Strategies
+    module Scraping
+      # Checks whether the conventional /favicon.ico path exists for a domain.
+      # Extracted from UrlNormalizer to respect SRP: URL normalization ≠ HTTP verification.
+      class DefaultFaviconChecker
+        extend T::Sig
+
+        sig { params(http_client: HttpClient).void }
+        def initialize(http_client:)
+          @http_client = T.let(http_client, HttpClient)
+        end
+
+        # Returns an Icon if the URL responds with 2xx, nil otherwise.
+        sig { params(url: String).returns(T.nilable(Icon)) }
+        def check(url)
+          return nil unless @http_client.head_success?(url)
+
+          Icon.new(
+            url: url,
+            dimensions: Config::DEFAULT_DIMENSIONS,
+            format: 'ico'
+          )
+        end
+      end
+    end
+  end
+end

data/lib/brand_logo/strategies/scraping/dimensions_extractor.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+# typed: strict
+
+require 'sorbet-runtime'
+
+module BrandLogo
+  module Strategies
+    module Scraping
+      # Extracts pixel dimensions from a favicon link element.
+      # Tries the HTML `sizes` attribute first (no network), then falls back
+      # to the injected ImageAnalyzer (may make a network request).
+      class DimensionsExtractor
+        extend T::Sig
+
+        sig { params(image_analyzer: ImageAnalyzer).void }
+        def initialize(image_analyzer:)
+          @image_analyzer = T.let(image_analyzer, ImageAnalyzer)
+        end
+
+        # Returns dimensions for the given link element and its resolved href.
+        sig { params(link: T.untyped, href: String).returns(T::Hash[Symbol, T.nilable(Integer)]) }
+        def extract(link, href)
+          extract_from_sizes_attribute(link) || @image_analyzer.dimensions(href)
+        end
+
+        private
+
+        # Parses the `sizes` HTML attribute (e.g. "32x32") without a network call.
+        sig { params(link: T.untyped).returns(T.nilable(T::Hash[Symbol, T.nilable(Integer)])) }
+        def extract_from_sizes_attribute(link)
+          sizes = link['sizes']&.split('x')
+          return nil unless sizes&.length == 2
+
+          width, height = T.cast(sizes, T::Array[String]).map(&:to_i)
+          return nil unless width.positive? && height.positive?
+
+          { width: width, height: height }
+        end
+      end
+    end
+  end
+end

data/lib/brand_logo/strategies/scraping/format_extractor.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+# typed: strict
+
+require 'sorbet-runtime'
+
+module BrandLogo
+  module Strategies
+    module Scraping
+      # Extracts format information from favicon link elements
+      class FormatExtractor
+        extend T::Sig
+
+        MIME_TO_FORMAT = T.let({
+          'image/x-icon' => 'ico',
+          'image/vnd.microsoft.icon' => 'ico',
+          'image/png' => 'png',
+          'image/svg+xml' => 'svg',
+          'image/jpeg' => 'jpg',
+          'image/webp' => 'webp'
+        }.freeze, T::Hash[String, String])
+
+        sig { params(link: Nokogiri::XML::Element).returns(String) }
+        def self.extract(link)
+          new(link).extract
+        end
+
+        sig { params(link: Nokogiri::XML::Element).void }
+        def initialize(link)
+          @link = link
+        end
+
+        sig { returns(String) }
+        def extract
+          extract_from_mime_type || extract_from_extension
+        end
+
+        private
+
+        sig { returns(T.nilable(String)) }
+        def extract_from_mime_type
+          return nil unless @link['type']
+
+          MIME_TO_FORMAT[@link['type']]
+        end
+
+        sig { returns(String) }
+        def extract_from_extension
+          extension = File.extname(@link['href']).delete('.').downcase
+          return 'ico' if extension.empty?
+
+          extension
+        end
+      end
+    end
+  end
+end

data/lib/brand_logo/strategies/scraping/icon_finder.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+# typed: strict
+
+require 'sorbet-runtime'
+
+module BrandLogo
+  module Strategies
+    module Scraping
+      # Finds all favicon candidates in a parsed HTML document.
+      # Returns unfiltered icons — validation/selection is the strategy's responsibility.
+      class IconFinder
+        extend T::Sig
+
+        FAVICON_SELECTORS = T.let([
+          'link[rel~="icon"]',
+          'link[rel~="shortcut"]',
+          'link[rel~="apple-touch-icon"]',
+          'link[rel~="mask-icon"]',
+          'link[type="image/x-icon"]',
+          'link[type="image/vnd.microsoft.icon"]',
+          'link[type="image/png"]',
+          'link[type="image/svg+xml"]'
+        ].freeze, T::Array[String])
+
+        sig do
+          params(
+            doc: ParsedDocument,
+            base_url: String,
+            dimensions_extractor: DimensionsExtractor,
+            default_favicon_checker: DefaultFaviconChecker
+          ).void
+        end
+        def initialize(doc:, base_url:, dimensions_extractor:, default_favicon_checker:)
+          @doc                      = T.let(doc, ParsedDocument)
+          @url_normalizer           = T.let(UrlNormalizer.new(base_url), UrlNormalizer)
+          @dimensions_extractor     = T.let(dimensions_extractor, DimensionsExtractor)
+          @default_favicon_checker  = T.let(default_favicon_checker, DefaultFaviconChecker)
+        end
+
+        # Returns all icons found in the document. Falls back to /favicon.ico if none.
+        sig { returns(T::Array[Icon]) }
+        def find
+          icons = find_icons_from_selectors
+          return icons unless icons.empty?
+
+          BrandLogo::Logging.logger.debug('No icons found in HTML, checking default /favicon.ico')
+          default_icon = @default_favicon_checker.check(@url_normalizer.default_favicon_url)
+          default_icon ? [default_icon] : []
+        end
+
+        private
+
+        sig { returns(T::Array[Icon]) }
+        def find_icons_from_selectors
+          FAVICON_SELECTORS.flat_map { |selector| process_selector(selector) }
+        end
+
+        sig { params(selector: String).returns(T::Array[Icon]) }
+        def process_selector(selector)
+          @doc.css(selector).filter_map { |link| build_icon_from_link(link) }
+        end
+
+        sig { params(link: T.untyped).returns(T.nilable(Icon)) }
+        def build_icon_from_link(link)
+          href = link['href']
+          return nil unless href
+
+          normalized_url = @url_normalizer.normalize(href)
+          dimensions     = @dimensions_extractor.extract(link, normalized_url)
+          format         = FormatExtractor.extract(link)
+
+          BrandLogo::Logging.logger.debug("Found icon: url=#{normalized_url} format=#{format} dimensions=#{dimensions}")
+
+          Icon.new(url: normalized_url, dimensions: dimensions, format: format)
+        end
+      end
+    end
+  end
+end

data/lib/brand_logo/strategies/scraping/url_normalizer.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+# typed: strict
+
+require 'sorbet-runtime'
+
+module BrandLogo
+  module Strategies
+    module Scraping
+      # Resolves favicon href values into absolute URLs.
+      # Pure string manipulation — no network calls (SRP).
+      # HTTP verification of the default favicon is handled by DefaultFaviconChecker.
+      class UrlNormalizer
+        extend T::Sig
+
+        sig { params(base_url: String).void }
+        def initialize(base_url)
+          @base_url = T.let(base_url, String)
+        end
+
+        # Returns an absolute URL, resolving relative hrefs against the base URL.
+        sig { params(href: String).returns(String) }
+        def normalize(href)
+          return href if absolute_url?(href)
+
+          join_with_base_url(href)
+        end
+
+        # Returns the conventional favicon path for the domain.
+        sig { returns(String) }
+        def default_favicon_url
+          "#{@base_url}#{Config::DEFAULT_FAVICON_PATH}"
+        end
+
+        private
+
+        sig { params(href: String).returns(T::Boolean) }
+        def absolute_url?(href)
+          href.start_with?('http://', 'https://')
+        end
+
+        sig { params(href: String).returns(String) }
+        def join_with_base_url(href)
+          URI.join(@base_url, href).to_s
+        rescue URI::Error
+          href
+        end
+      end
+    end
+  end
+end

data/lib/brand_logo/strategies/scraping_strategy.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+# typed: strict
+
+require 'sorbet-runtime'
+
+module BrandLogo
+  module Strategies
+    # Fetches brand logos by scraping the target website's HTML.
+    # Tries HTTPS (with and without www), then falls back to HTTP.
+    # Delegates HTML fetching, parsing, and image analysis to injected dependencies.
+    class ScrapingStrategy < BaseStrategy
+      extend T::Sig
+
+      sig do
+        params(
+          config: Config,
+          http_client: HttpClient,
+          html_parser: HtmlParser,
+          image_analyzer: ImageAnalyzer
+        ).void
+      end
+      def initialize(config:, http_client:, html_parser:, image_analyzer:)
+        super(config: config)
+        @http_client    = T.let(http_client, HttpClient)
+        @html_parser    = T.let(html_parser, HtmlParser)
+        @image_analyzer = T.let(image_analyzer, ImageAnalyzer)
+      end
+
+      sig { override.params(domain: String).returns(T::Array[Icon]) }
+      def fetch_all(domain)
+        html, base_url = fetch_html_with_base_url(domain)
+        return [] unless html
+
+        dimensions_extractor    = Scraping::DimensionsExtractor.new(image_analyzer: @image_analyzer)
+        default_favicon_checker = Scraping::DefaultFaviconChecker.new(http_client: @http_client)
+
+        finder = Scraping::IconFinder.new(
+          doc: @html_parser.parse(html),
+          base_url: base_url,
+          dimensions_extractor: dimensions_extractor,
+          default_favicon_checker: default_favicon_checker
+        )
+        finder.find
+      rescue StandardError => e
+        BrandLogo::Logging.logger.error("ScrapingStrategy error for #{domain}: #{e.message}")
+        []
+      end
+
+      private
+
+      # Returns [html_body, base_url] for the first responding URL candidate, or nil.
+      sig { params(domain: String).returns(T.nilable([String, String])) }
+      def fetch_html_with_base_url(domain)
+        url_candidates(domain).each do |url|
+          body = @http_client.get_body(url)
+          next unless body
+
+          BrandLogo::Logging.logger.debug("Fetched HTML from #{url}")
+          return [body, url]
+        end
+
+        BrandLogo::Logging.logger.debug("Could not fetch HTML for #{domain}")
+        nil
+      end
+
+      # Ordered list of URLs to try: HTTPS without www, HTTPS with www, HTTP fallback.
+      sig { params(domain: String).returns(T::Array[String]) }
+      def url_candidates(domain)
+        [
+          "https://#{domain}",
+          "https://www.#{domain}",
+          "http://#{domain}"
+        ]
+      end
+    end
+  end
+end

data/lib/brand_logo/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+# typed: strict
+
+module BrandLogo
+  VERSION = '1.0.0'
+end

data/lib/brand_logo.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+# typed: strict
+
+require 'sorbet-runtime'
+
+# Foundation
+require_relative 'brand_logo/version'
+require_relative 'brand_logo/errors'
+require_relative 'brand_logo/config'
+require_relative 'brand_logo/logging'
+
+# Interfaces & implementations
+require_relative 'brand_logo/http_client'
+require_relative 'brand_logo/image_analyzer'
+require_relative 'brand_logo/html_parser'
+
+# Domain model
+require_relative 'brand_logo/icon'
+
+# Strategies — base must be loaded before subclasses
+require_relative 'brand_logo/strategies/base_strategy'
+
+# Scraping utilities (loaded before strategies that use them)
+require_relative 'brand_logo/strategies/scraping/format_extractor'
+require_relative 'brand_logo/strategies/scraping/url_normalizer'
+require_relative 'brand_logo/strategies/scraping/dimensions_extractor'
+require_relative 'brand_logo/strategies/scraping/default_favicon_checker'
+require_relative 'brand_logo/strategies/scraping/icon_finder'
+
+# Concrete strategies
+require_relative 'brand_logo/strategies/scraping_strategy'
+require_relative 'brand_logo/strategies/duckduckgo_strategy'
+require_relative 'brand_logo/strategies/meta_tag_strategy'
+require_relative 'brand_logo/strategies/manifest_strategy'
+
+# Entry point
+require_relative 'brand_logo/fetcher'