blog_verification 1.0.0

data/lib/blog_verification/adapters/medium_adapter.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'base_adapter'
+require_relative '../utils/url_security'
+require_relative '../utils/normalizer'
+require_relative '../errors'
+require_relative '../constants/error_codes'
+
+module BlogVerification
+  module Adapters
+    class MediumAdapter < BaseAdapter
+      def initialize
+        super('medium')
+      end
+
+      # Extracts canonical username from a username string, identifier, or Medium author URL.
+      # Medium canonical usernames are formatted as @username or bare username identifiers.
+      def extract_username(input)
+        return nil if input.nil? || !input.is_a?(String)
+
+        trimmed = input.strip
+
+        # 1. @username in URL or path (e.g. https://medium.com/@thedevankit or @thedevankit)
+        at_match = trimmed.match(/@([a-zA-Z0-9_.-]+)/)
+        return at_match[1] if at_match && at_match[1]
+
+        # 2. Subdomain URL (e.g. https://thedevankit.medium.com)
+        sub_match = trimmed.match(%r{\Ahttps?://([a-zA-Z0-9_-]+)\.medium\.com}i)
+        if sub_match && sub_match[1] && !%w[www api cdn-images-1].include?(sub_match[1].downcase)
+          return sub_match[1]
+        end
+
+        # 3. Clean bare username / identifier string (e.g. "thedevankit")
+        if !trimmed.include?('/') && !trimmed.include?(':') && trimmed.match?(/\A[a-zA-Z0-9_.-]+\z/)
+          return trimmed.sub(/\A@/, '')
+        end
+
+        nil
+      end
+
+      # Extracts article body HTML/text content from Medium page
+      def extract_article_content(html)
+        return nil if html.nil? || !html.is_a?(String)
+
+        article_match = html.match(%r{<article\b[^>]*>([\s\S]*?)</article>}i)
+        return article_match[1] if article_match
+
+        p_matches = html.scan(%r{<p\b[^>]*>([\s\S]*?)</p>}i).flatten
+        return p_matches.join(' ') unless p_matches.empty?
+
+        nil
+      end
+
+      # Parses JSON-LD script blocks from HTML string
+      def parse_json_ld(html)
+        blocks = []
+        return blocks if html.nil? || !html.is_a?(String)
+
+        # Match script tags with type application/ld+json
+        regex = %r{<script\b[^>]*\btype=["']application/ld\+json["'][^>]*>([\s\S]*?)</script>}i
+        html.scan(regex) do |match|
+          content = match[0]
+          begin
+            parsed = JSON.parse(content)
+            if parsed.is_a?(Array)
+              blocks.concat(parsed)
+            elsif parsed.is_a?(Hash)
+              if parsed['@graph'].is_a?(Array)
+                blocks.concat(parsed['@graph'])
+              else
+                blocks << parsed
+              end
+            end
+          rescue JSON::ParserError
+            # Skip invalid JSON-LD block
+          end
+        end
+
+        blocks
+      end
+
+      # Extracts meta tag attributes from HTML
+      def parse_meta_tags(html)
+        meta = {
+          published_time: nil,
+          author_url: nil,
+          author_name: nil,
+          description: nil,
+          canonical_url: nil,
+          tags: []
+        }
+
+        return meta if html.nil? || !html.is_a?(String)
+
+        meta_regex = /<meta\s+([^>]+)>/i
+        html.scan(meta_regex) do |match|
+          tag_content = match[0]
+
+          get_attr = lambda do |name|
+            m = tag_content.match(/#{name}=["']([^"']*)["']/i)
+            m ? m[1] : nil
+          end
+
+          prop = get_attr.call('property') || get_attr.call('name')
+          content = get_attr.call('content')
+
+          next unless prop && content
+
+          lower_prop = prop.downcase
+          case lower_prop
+          when 'article:published_time'
+            meta[:published_time] = content
+          when 'article:author'
+            meta[:author_url] = content
+          when 'author'
+            meta[:author_name] = content
+          when 'description'
+            meta[:description] ||= content
+          when 'og:description'
+            meta[:description] ||= content
+          when 'article:tag'
+            meta[:tags] << content
+          end
+        end
+
+        canonical_match = html.match(%r{<link\s+rel=["']canonical["']\s+href=["']([^"']+)["']}i)
+        meta[:canonical_url] = canonical_match[1] if canonical_match
+
+        meta
+      end
+
+      # Retrieves and normalizes metadata for a Medium article
+      def get_article_metadata(url, _options = {})
+        Utils::UrlSecurity.validate_article_url(url, 'medium')
+
+        response = Utils::UrlSecurity.safe_fetch(
+          url,
+          {
+            headers: {
+              'Accept' => 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+              'User-Agent' => 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36 BlogVerificationAPI/1.0'
+            }
+          },
+          'medium'
+        )
+
+        case response.status
+        when 404
+          raise UpstreamError.new(ErrorCodes::ARTICLE_NOT_FOUND, 'The specified article does not exist on Medium.', 404)
+        when 401, 403
+          raise UpstreamError.new(ErrorCodes::ARTICLE_ACCESS_DENIED, 'Access to Medium article is restricted.', response.status)
+        when 429
+          raise UpstreamError.new(ErrorCodes::SOURCE_RATE_LIMITED, 'Medium rate limit exceeded.', 429)
+        else
+          if response.status >= 500
+            raise UpstreamError.new(ErrorCodes::SOURCE_UNAVAILABLE, "Medium returned HTTP #{response.status}.", response.status)
+          elsif !response.ok?
+            raise UpstreamError.new(ErrorCodes::SOURCE_RESPONSE_INVALID, "Medium returned HTTP #{response.status}.", response.status)
+          end
+        end
+
+        html = response.text
+        meta_tags = parse_meta_tags(html)
+        json_ld_blocks = parse_json_ld(html)
+
+        # 1. Locate article JSON-LD block and author block
+        author_obj = nil
+        article_block = json_ld_blocks.find do |b|
+          %w[NewsArticle BlogPosting Article TechArticle].include?(b['@type'])
+        end
+
+        if article_block && article_block['author']
+          author_obj = article_block['author'].is_a?(Array) ? article_block['author'][0] : article_block['author']
+        end
+
+        # Inspect all blocks if author not found in article block
+        unless author_obj
+          json_ld_blocks.each do |b|
+            if b.is_a?(Hash) && b['author']
+              author_obj = b['author'].is_a?(Array) ? b['author'][0] : b['author']
+              article_block ||= b
+              break
+            elsif b.is_a?(Hash) && b['@type'] == 'Person'
+              author_obj = b
+              break
+            end
+          end
+        end
+
+        article_block ||= json_ld_blocks[0] || {}
+
+        # Canonical URL
+        canonical_url = meta_tags[:canonical_url] || article_block['mainEntityOfPage'] || article_block['url'] || url
+
+        # Canonical Author Extraction
+        canonical_username = nil
+        display_name = nil
+
+        if author_obj
+          if author_obj.is_a?(Hash)
+            display_name = author_obj['name']
+
+            # 1. Identifier
+            canonical_username = extract_username(author_obj['identifier']) if author_obj['identifier']
+            # 2. @id
+            canonical_username ||= extract_username(author_obj['@id']) if author_obj['@id']
+            # 3. url
+            canonical_username ||= extract_username(author_obj['url']) if author_obj['url']
+          elsif author_obj.is_a?(String)
+            canonical_username = extract_username(author_obj)
+          end
+        end
+
+        # Fallbacks to meta tags or article URL
+        if !canonical_username && meta_tags[:author_url]
+          canonical_username = extract_username(meta_tags[:author_url])
+        end
+
+        canonical_username ||= extract_username(canonical_url) || extract_username(url)
+        display_name ||= meta_tags[:author_name]
+
+        # Publication date
+        published_at = article_block['datePublished'] ||
+                       (json_ld_blocks[0] && json_ld_blocks[0]['datePublished']) ||
+                       meta_tags[:published_time]
+
+        updated_at = article_block['dateModified'] ||
+                     (json_ld_blocks[0] && json_ld_blocks[0]['dateModified'])
+
+        # Description / Summary
+        description = article_block['description'] ||
+                      (json_ld_blocks[0] && json_ld_blocks[0]['description']) ||
+                      meta_tags[:description]
+
+        # Tags / Keywords
+        raw_keywords = article_block['keywords'] || (json_ld_blocks[0] && json_ld_blocks[0]['keywords'])
+        tags = if raw_keywords.is_a?(Array)
+                 raw_keywords
+               elsif raw_keywords.is_a?(String)
+                 raw_keywords.split(',').map(&:strip).reject(&:empty?)
+               elsif !meta_tags[:tags].empty?
+                 meta_tags[:tags]
+               end
+
+        content = extract_article_content(html)
+        word_count = content ? Utils::Normalizer.count_words(content) : nil
+
+        {
+          canonical_url: canonical_url,
+          platform: 'medium',
+          author: {
+            username: canonical_username,
+            display_name: display_name
+          },
+          published_at: published_at,
+          updated_at: updated_at,
+          tags: tags,
+          topic: nil,
+          description: description,
+          content: content,
+          word_count: word_count,
+          raw_metadata: {
+            meta_tags: meta_tags,
+            article_block: article_block
+          }
+        }
+      end
+    end
+  end
+end

data/lib/blog_verification/configuration.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module BlogVerification
+  class Configuration
+    attr_accessor :request_timeout, :max_redirects, :user_agent, :skip_dns_check, :require_https
+
+    def initialize
+      @request_timeout = 5.0 # seconds
+      @max_redirects = 5
+      @user_agent = "BlogVerificationRubyGem/#{BlogVerification::VERSION} (+https://github.com/example/blog_verification)"
+      @skip_dns_check = ENV['SKIP_DNS_CHECK'] == 'true'
+      @require_https = true
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration) if block_given?
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/blog_verification/constants/error_codes.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module BlogVerification
+  module ErrorCodes
+    # Top-level verification outcomes
+    module VerificationStatus
+      VALID = 'valid'
+      INVALID = 'invalid'
+      UNVERIFIED = 'unverified'
+    end
+
+    # Individual field check status
+    module CheckStatus
+      PASSED = 'passed'
+      FAILED = 'failed'
+      SKIPPED = 'skipped'
+      UNVERIFIED = 'unverified'
+    end
+
+    # Standard error codes
+    INVALID_REQUEST              = 'INVALID_REQUEST'
+    MISSING_REQUIRED_FIELD       = 'MISSING_REQUIRED_FIELD'
+    INVALID_PLATFORM             = 'INVALID_PLATFORM'
+    INVALID_URL                  = 'INVALID_URL'
+    UNSAFE_URL                   = 'UNSAFE_URL'
+    ARTICLE_NOT_FOUND            = 'ARTICLE_NOT_FOUND'
+    ARTICLE_ACCESS_DENIED        = 'ARTICLE_ACCESS_DENIED'
+    AUTHOR_MISMATCH              = 'AUTHOR_MISMATCH'
+    PUBLICATION_DATE_MISMATCH    = 'PUBLICATION_DATE_MISMATCH'
+    NOT_IN_CURRENT_QUARTER       = 'NOT_IN_CURRENT_QUARTER'
+    TAGS_MISMATCH                = 'TAGS_MISMATCH'
+    TOPIC_MISMATCH               = 'TOPIC_MISMATCH'
+    SUMMARY_MISMATCH             = 'SUMMARY_MISMATCH'
+    INSUFFICIENT_CONTENT_LENGTH  = 'INSUFFICIENT_CONTENT_LENGTH'
+    SOURCE_METADATA_UNAVAILABLE  = 'SOURCE_METADATA_UNAVAILABLE'
+    SOURCE_RATE_LIMITED          = 'SOURCE_RATE_LIMITED'
+    SOURCE_TIMEOUT               = 'SOURCE_TIMEOUT'
+    SOURCE_UNAVAILABLE           = 'SOURCE_UNAVAILABLE'
+    SOURCE_RESPONSE_INVALID      = 'SOURCE_RESPONSE_INVALID'
+    INTERNAL_ERROR               = 'INTERNAL_ERROR'
+
+    DEFAULT_ERROR_MESSAGES = {
+      INVALID_REQUEST => 'The verification request body is malformed or invalid JSON.',
+      MISSING_REQUIRED_FIELD => 'A required request field is missing.',
+      INVALID_PLATFORM => 'The requested platform is not supported. Supported platforms: devto, medium.',
+      INVALID_URL => 'The submitted URL is invalid, uses an unapproved host, or targets an unsupported path.',
+      UNSAFE_URL => 'The submitted URL or a redirect destination targets an unapproved or private network address.',
+      ARTICLE_NOT_FOUND => 'The requested article could not be found on the platform.',
+      ARTICLE_ACCESS_DENIED => 'The article cannot be verified because of access restrictions or paywalls.',
+      AUTHOR_MISMATCH => 'The submitted username does not match the blog author.',
+      PUBLICATION_DATE_MISMATCH => "The submitted publication date does not match the blog's publication date.",
+      NOT_IN_CURRENT_QUARTER => 'The blog publication date is not in the current quarter.',
+      TAGS_MISMATCH => "The submitted tags do not match the blog's tags.",
+      TOPIC_MISMATCH => "The submitted topic does not match the blog's topic.",
+      SUMMARY_MISMATCH => "The submitted summary does not match the blog's description.",
+      INSUFFICIENT_CONTENT_LENGTH => 'The blog content does not meet the minimum required word count of 500 words.',
+      SOURCE_METADATA_UNAVAILABLE => 'Required metadata could not be retrieved from the source platform.',
+      SOURCE_RATE_LIMITED => 'Verification is temporarily unavailable due to upstream rate limits.',
+      SOURCE_TIMEOUT => 'The source platform did not respond within the allowed time.',
+      SOURCE_UNAVAILABLE => 'The source platform is temporarily unavailable.',
+      SOURCE_RESPONSE_INVALID => 'The response from the source platform could not be parsed.',
+      INTERNAL_ERROR => 'An unexpected internal error occurred during verification.'
+    }.freeze
+  end
+end

data/lib/blog_verification/constants/taxonomy.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+module BlogVerification
+  module Taxonomy
+    CANONICAL_TOPICS = {
+      BACKEND_DEVELOPMENT: 'Backend Development',
+      FRONTEND_DEVELOPMENT: 'Frontend Development',
+      FULL_STACK_DEVELOPMENT: 'Full Stack Development',
+      DEVOPS_CLOUD: 'DevOps & Cloud',
+      AI_MACHINE_LEARNING: 'Artificial Intelligence & Machine Learning',
+      MOBILE_DEVELOPMENT: 'Mobile Development',
+      CYBERSECURITY: 'Cybersecurity',
+      DATABASE_DATA_ENGINEERING: 'Database & Data Engineering',
+      SOFTWARE_ARCHITECTURE: 'Software Architecture & Design',
+      PROGRAMMING_LANGUAGES: 'Programming Languages',
+      TESTING_QA: 'Testing & Quality Assurance',
+      WEB_DEVELOPMENT: 'Web Development'
+    }.freeze
+
+    # Aliases and tag keywords mapped deterministically to canonical topics
+    TAG_TO_TOPIC_MAP = {
+      # Backend Development
+      'nodejs' => CANONICAL_TOPICS[:BACKEND_DEVELOPMENT],
+      'node' => CANONICAL_TOPICS[:BACKEND_DEVELOPMENT],
+      'express' => CANONICAL_TOPICS[:BACKEND_DEVELOPMENT],
+      'expressjs' => CANONICAL_TOPICS[:BACKEND_DEVELOPMENT],
+      'api' => CANONICAL_TOPICS[:BACKEND_DEVELOPMENT],
+      'rest-api' => CANONICAL_TOPICS[:BACKEND_DEVELOPMENT],
+      'rest' => CANONICAL_TOPICS[:BACKEND_DEVELOPMENT],
+      'backend' => CANONICAL_TOPICS[:BACKEND_DEVELOPMENT],
+      'fastapi' => CANONICAL_TOPICS[:BACKEND_DEVELOPMENT],
+      'django' => CANONICAL_TOPICS[:BACKEND_DEVELOPMENT],
+      'flask' => CANONICAL_TOPICS[:BACKEND_DEVELOPMENT],
+      'spring' => CANONICAL_TOPICS[:BACKEND_DEVELOPMENT],
+      'springboot' => CANONICAL_TOPICS[:BACKEND_DEVELOPMENT],
+      'nestjs' => CANONICAL_TOPICS[:BACKEND_DEVELOPMENT],
+      'graphql' => CANONICAL_TOPICS[:BACKEND_DEVELOPMENT],
+      'microservices' => CANONICAL_TOPICS[:BACKEND_DEVELOPMENT],
+      'rails' => CANONICAL_TOPICS[:BACKEND_DEVELOPMENT],
+      'ruby-on-rails' => CANONICAL_TOPICS[:BACKEND_DEVELOPMENT],
+
+      # Frontend Development
+      'frontend' => CANONICAL_TOPICS[:FRONTEND_DEVELOPMENT],
+      'react' => CANONICAL_TOPICS[:FRONTEND_DEVELOPMENT],
+      'reactjs' => CANONICAL_TOPICS[:FRONTEND_DEVELOPMENT],
+      'vue' => CANONICAL_TOPICS[:FRONTEND_DEVELOPMENT],
+      'vuejs' => CANONICAL_TOPICS[:FRONTEND_DEVELOPMENT],
+      'angular' => CANONICAL_TOPICS[:FRONTEND_DEVELOPMENT],
+      'svelte' => CANONICAL_TOPICS[:FRONTEND_DEVELOPMENT],
+      'css' => CANONICAL_TOPICS[:FRONTEND_DEVELOPMENT],
+      'html' => CANONICAL_TOPICS[:FRONTEND_DEVELOPMENT],
+      'tailwind' => CANONICAL_TOPICS[:FRONTEND_DEVELOPMENT],
+      'nextjs' => CANONICAL_TOPICS[:FRONTEND_DEVELOPMENT],
+
+      # DevOps & Cloud
+      'devops' => CANONICAL_TOPICS[:DEVOPS_CLOUD],
+      'cloud' => CANONICAL_TOPICS[:DEVOPS_CLOUD],
+      'aws' => CANONICAL_TOPICS[:DEVOPS_CLOUD],
+      'gcp' => CANONICAL_TOPICS[:DEVOPS_CLOUD],
+      'azure' => CANONICAL_TOPICS[:DEVOPS_CLOUD],
+      'docker' => CANONICAL_TOPICS[:DEVOPS_CLOUD],
+      'kubernetes' => CANONICAL_TOPICS[:DEVOPS_CLOUD],
+      'k8s' => CANONICAL_TOPICS[:DEVOPS_CLOUD],
+      'ci-cd' => CANONICAL_TOPICS[:DEVOPS_CLOUD],
+      'cicd' => CANONICAL_TOPICS[:DEVOPS_CLOUD],
+      'terraform' => CANONICAL_TOPICS[:DEVOPS_CLOUD],
+
+      # AI & Machine Learning
+      'ai' => CANONICAL_TOPICS[:AI_MACHINE_LEARNING],
+      'artificial-intelligence' => CANONICAL_TOPICS[:AI_MACHINE_LEARNING],
+      'machine-learning' => CANONICAL_TOPICS[:AI_MACHINE_LEARNING],
+      'ml' => CANONICAL_TOPICS[:AI_MACHINE_LEARNING],
+      'deep-learning' => CANONICAL_TOPICS[:AI_MACHINE_LEARNING],
+      'llm' => CANONICAL_TOPICS[:AI_MACHINE_LEARNING],
+      'datascience' => CANONICAL_TOPICS[:AI_MACHINE_LEARNING],
+      'data-science' => CANONICAL_TOPICS[:AI_MACHINE_LEARNING],
+      'nlp' => CANONICAL_TOPICS[:AI_MACHINE_LEARNING],
+      'prompt-engineering' => CANONICAL_TOPICS[:AI_MACHINE_LEARNING],
+
+      # Mobile Development
+      'mobile' => CANONICAL_TOPICS[:MOBILE_DEVELOPMENT],
+      'android' => CANONICAL_TOPICS[:MOBILE_DEVELOPMENT],
+      'ios' => CANONICAL_TOPICS[:MOBILE_DEVELOPMENT],
+      'flutter' => CANONICAL_TOPICS[:MOBILE_DEVELOPMENT],
+      'react-native' => CANONICAL_TOPICS[:MOBILE_DEVELOPMENT],
+      'swift' => CANONICAL_TOPICS[:MOBILE_DEVELOPMENT],
+      'kotlin' => CANONICAL_TOPICS[:MOBILE_DEVELOPMENT],
+
+      # Cybersecurity
+      'security' => CANONICAL_TOPICS[:CYBERSECURITY],
+      'cybersecurity' => CANONICAL_TOPICS[:CYBERSECURITY],
+      'infosec' => CANONICAL_TOPICS[:CYBERSECURITY],
+      'auth' => CANONICAL_TOPICS[:CYBERSECURITY],
+      'authentication' => CANONICAL_TOPICS[:CYBERSECURITY],
+      'oauth' => CANONICAL_TOPICS[:CYBERSECURITY],
+      'jwt' => CANONICAL_TOPICS[:CYBERSECURITY],
+      'cryptography' => CANONICAL_TOPICS[:CYBERSECURITY],
+
+      # Database & Data Engineering
+      'database' => CANONICAL_TOPICS[:DATABASE_DATA_ENGINEERING],
+      'databases' => CANONICAL_TOPICS[:DATABASE_DATA_ENGINEERING],
+      'sql' => CANONICAL_TOPICS[:DATABASE_DATA_ENGINEERING],
+      'postgresql' => CANONICAL_TOPICS[:DATABASE_DATA_ENGINEERING],
+      'postgres' => CANONICAL_TOPICS[:DATABASE_DATA_ENGINEERING],
+      'mysql' => CANONICAL_TOPICS[:DATABASE_DATA_ENGINEERING],
+      'mongodb' => CANONICAL_TOPICS[:DATABASE_DATA_ENGINEERING],
+      'nosql' => CANONICAL_TOPICS[:DATABASE_DATA_ENGINEERING],
+      'redis' => CANONICAL_TOPICS[:DATABASE_DATA_ENGINEERING],
+
+      # Software Architecture & Design
+      'architecture' => CANONICAL_TOPICS[:SOFTWARE_ARCHITECTURE],
+      'system-design' => CANONICAL_TOPICS[:SOFTWARE_ARCHITECTURE],
+      'design-patterns' => CANONICAL_TOPICS[:SOFTWARE_ARCHITECTURE],
+      'software-architecture' => CANONICAL_TOPICS[:SOFTWARE_ARCHITECTURE],
+      'unix' => CANONICAL_TOPICS[:SOFTWARE_ARCHITECTURE],
+
+      # Programming Languages
+      'programming' => CANONICAL_TOPICS[:PROGRAMMING_LANGUAGES],
+      'javascript' => CANONICAL_TOPICS[:PROGRAMMING_LANGUAGES],
+      'typescript' => CANONICAL_TOPICS[:PROGRAMMING_LANGUAGES],
+      'python' => CANONICAL_TOPICS[:PROGRAMMING_LANGUAGES],
+      'ruby' => CANONICAL_TOPICS[:PROGRAMMING_LANGUAGES],
+      'rust' => CANONICAL_TOPICS[:PROGRAMMING_LANGUAGES],
+      'golang' => CANONICAL_TOPICS[:PROGRAMMING_LANGUAGES],
+      'go' => CANONICAL_TOPICS[:PROGRAMMING_LANGUAGES],
+      'java' => CANONICAL_TOPICS[:PROGRAMMING_LANGUAGES],
+      'csharp' => CANONICAL_TOPICS[:PROGRAMMING_LANGUAGES],
+      'cpp' => CANONICAL_TOPICS[:PROGRAMMING_LANGUAGES],
+
+      # Testing & QA
+      'testing' => CANONICAL_TOPICS[:TESTING_QA],
+      'qa' => CANONICAL_TOPICS[:TESTING_QA],
+      'unit-testing' => CANONICAL_TOPICS[:TESTING_QA],
+      'jest' => CANONICAL_TOPICS[:TESTING_QA],
+      'cypress' => CANONICAL_TOPICS[:TESTING_QA],
+      'rspec' => CANONICAL_TOPICS[:TESTING_QA],
+
+      # Web Development
+      'webdev' => CANONICAL_TOPICS[:WEB_DEVELOPMENT],
+      'web-development' => CANONICAL_TOPICS[:WEB_DEVELOPMENT]
+    }.freeze
+
+    # Aliases for topic names to canonical names
+    TOPIC_SYNONYMS = {
+      'backend' => CANONICAL_TOPICS[:BACKEND_DEVELOPMENT],
+      'backend development' => CANONICAL_TOPICS[:BACKEND_DEVELOPMENT],
+      'frontend' => CANONICAL_TOPICS[:FRONTEND_DEVELOPMENT],
+      'frontend development' => CANONICAL_TOPICS[:FRONTEND_DEVELOPMENT],
+      'fullstack' => CANONICAL_TOPICS[:FULL_STACK_DEVELOPMENT],
+      'full stack' => CANONICAL_TOPICS[:FULL_STACK_DEVELOPMENT],
+      'full stack development' => CANONICAL_TOPICS[:FULL_STACK_DEVELOPMENT],
+      'devops' => CANONICAL_TOPICS[:DEVOPS_CLOUD],
+      'devops & cloud' => CANONICAL_TOPICS[:DEVOPS_CLOUD],
+      'cloud' => CANONICAL_TOPICS[:DEVOPS_CLOUD],
+      'ai' => CANONICAL_TOPICS[:AI_MACHINE_LEARNING],
+      'machine learning' => CANONICAL_TOPICS[:AI_MACHINE_LEARNING],
+      'ai & machine learning' => CANONICAL_TOPICS[:AI_MACHINE_LEARNING],
+      'artificial intelligence' => CANONICAL_TOPICS[:AI_MACHINE_LEARNING],
+      'artificial intelligence & machine learning' => CANONICAL_TOPICS[:AI_MACHINE_LEARNING],
+      'data science & ai' => CANONICAL_TOPICS[:AI_MACHINE_LEARNING],
+      'mobile' => CANONICAL_TOPICS[:MOBILE_DEVELOPMENT],
+      'mobile development' => CANONICAL_TOPICS[:MOBILE_DEVELOPMENT],
+      'security' => CANONICAL_TOPICS[:CYBERSECURITY],
+      'cybersecurity' => CANONICAL_TOPICS[:CYBERSECURITY],
+      'database' => CANONICAL_TOPICS[:DATABASE_DATA_ENGINEERING],
+      'database & data engineering' => CANONICAL_TOPICS[:DATABASE_DATA_ENGINEERING],
+      'architecture' => CANONICAL_TOPICS[:SOFTWARE_ARCHITECTURE],
+      'software architecture' => CANONICAL_TOPICS[:SOFTWARE_ARCHITECTURE],
+      'software architecture & design' => CANONICAL_TOPICS[:SOFTWARE_ARCHITECTURE],
+      'programming' => CANONICAL_TOPICS[:PROGRAMMING_LANGUAGES],
+      'programming languages' => CANONICAL_TOPICS[:PROGRAMMING_LANGUAGES],
+      'testing' => CANONICAL_TOPICS[:TESTING_QA],
+      'testing & qa' => CANONICAL_TOPICS[:TESTING_QA],
+      'testing & quality assurance' => CANONICAL_TOPICS[:TESTING_QA],
+      'webdev' => CANONICAL_TOPICS[:WEB_DEVELOPMENT],
+      'web development' => CANONICAL_TOPICS[:WEB_DEVELOPMENT]
+    }.freeze
+
+    class << self
+      def normalize_topic_string(str)
+        return '' unless str.is_a?(String)
+
+        str.strip.downcase.gsub(/\s+/, ' ')
+      end
+
+      def resolve_canonical_topic(topic_str)
+        normalized = normalize_topic_string(topic_str)
+        return nil if normalized.empty?
+
+        TOPIC_SYNONYMS[normalized]
+      end
+
+      def derive_topic_from_metadata(metadata)
+        return nil unless metadata.is_a?(Hash)
+
+        # 1. Authoritative topic/category if present
+        topic_val = metadata[:topic] || metadata['topic']
+        if topic_val && !topic_val.to_s.strip.empty?
+          canonical = resolve_canonical_topic(topic_val.to_s)
+          return canonical || topic_val.to_s.strip
+        end
+
+        # 2. Derive from tags
+        tags = metadata[:tags] || metadata['tags']
+        return nil unless tags.is_a?(Array) && !tags.empty?
+
+        topic_counts = Hash.new(0)
+        tags.each do |tag|
+          norm_tag = tag.to_s.strip.downcase
+          mapped = TAG_TO_TOPIC_MAP[norm_tag]
+          topic_counts[mapped] += 1 if mapped
+        end
+
+        return nil if topic_counts.empty?
+
+        # Pick topic with most occurrences (or first on tie)
+        sorted = topic_counts.sort_by { |_topic, count| -count }
+        sorted.first[0]
+      end
+
+      def compare_topics(expected_topic, verified_topic)
+        return false if expected_topic.nil? || verified_topic.nil?
+
+        norm_expected = normalize_topic_string(expected_topic.to_s)
+        norm_verified = normalize_topic_string(verified_topic.to_s)
+
+        return true if norm_expected == norm_verified
+
+        canonical_expected = resolve_canonical_topic(expected_topic.to_s)
+        canonical_verified = resolve_canonical_topic(verified_topic.to_s)
+
+        if canonical_expected && canonical_verified && canonical_expected == canonical_verified
+          return true
+        end
+
+        if canonical_expected && normalize_topic_string(canonical_expected) == norm_verified
+          return true
+        end
+
+        if canonical_verified && normalize_topic_string(canonical_verified) == norm_expected
+          return true
+        end
+
+        false
+      end
+    end
+  end
+end

data/lib/blog_verification/errors.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative 'constants/error_codes'
+
+module BlogVerification
+  class Error < StandardError
+    attr_reader :error_code, :field, :details
+
+    def initialize(error_code, message = nil, field = nil, details = {})
+      @error_code = error_code
+      @field = field
+      @details = details || {}
+      msg = message || ErrorCodes::DEFAULT_ERROR_MESSAGES[error_code] || 'An error occurred.'
+      super(msg)
+    end
+  end
+
+  class ValidationError < Error; end
+
+  class UpstreamError < Error
+    attr_reader :status_code
+
+    def initialize(error_code, message = nil, status_code = nil, details = {})
+      @status_code = status_code
+      super(error_code, message, nil, details)
+    end
+  end
+
+  class SSRFError < Error
+    def initialize(message = 'The target host or IP is private or restricted.')
+      super(ErrorCodes::UNSAFE_URL, message, 'url')
+    end
+  end
+end

data/lib/blog_verification/rails/railtie.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module BlogVerification
+  module Rails
+    class Railtie < ::Rails::Railtie
+      initializer 'blog_verification.active_model_validator' do
+        ::ActiveSupport.on_load(:active_record) do
+          require_relative 'validator'
+        end
+      end
+    end
+  end
+end