blog_verification 1.0.0

data/lib/blog_verification/services/verification_service.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+require_relative '../constants/error_codes'
+require_relative '../errors'
+require_relative '../utils/url_security'
+require_relative '../utils/date_helper'
+require_relative '../adapters/devto_adapter'
+require_relative '../adapters/medium_adapter'
+require_relative 'validation_service'
+
+module BlogVerification
+  module Services
+    class VerificationService
+      include ErrorCodes
+
+      attr_reader :adapters, :validation_service
+
+      def initialize(adapters = nil, validation_service = nil)
+        @adapters = adapters || {
+          'devto' => Adapters::DevtoAdapter.new,
+          'medium' => Adapters::MediumAdapter.new
+        }
+        @validation_service = validation_service || ValidationService.new
+      end
+
+      # Validates input attributes and returns { valid: boolean, errors: [...], sanitized: {...} }
+      def validate_input(params)
+        errors = []
+        unless params.is_a?(Hash)
+          return {
+            valid: false,
+            errors: [
+              {
+                'code' => INVALID_REQUEST,
+                'field' => nil,
+                'message' => 'Verification input must be a Hash or Object.'
+              }
+            ]
+          }
+        end
+
+        # Normalize keys to string
+        h = {}
+        params.each { |k, v| h[k.to_s] = v }
+
+        platform = h['platform']
+        url = h['url']
+        username = h['username']
+        published_at = h['publishedAt'] || h['published_at']
+        topic = h['topic']
+        summary = h['summary']
+        tags = h['tags']
+        min_word_count = h['minWordCount'] || h['min_word_count']
+        reference_date = h['referenceDate'] || h['reference_date']
+
+        # 1. Platform validation
+        if platform.nil? || platform.to_s.strip.empty?
+          errors << {
+            'code' => MISSING_REQUIRED_FIELD,
+            'field' => 'platform',
+            'message' => 'Platform is required.'
+          }
+        else
+          plat = platform.to_s.downcase.strip
+          unless %w[devto medium].include?(plat)
+            errors << {
+              'code' => INVALID_PLATFORM,
+              'field' => 'platform',
+              'message' => "Platform must be either 'medium' or 'devto'."
+            }
+          end
+        end
+
+        # 2. URL validation
+        if url.nil? || url.to_s.strip.empty?
+          errors << {
+            'code' => MISSING_REQUIRED_FIELD,
+            'field' => 'url',
+            'message' => 'URL is required.'
+          }
+        end
+
+        # 3. Username validation
+        if username.nil? || username.to_s.strip.empty?
+          errors << {
+            'code' => MISSING_REQUIRED_FIELD,
+            'field' => 'username',
+            'message' => 'Username is required.'
+          }
+        end
+
+        # 4. publishedAt validation
+        if published_at.nil? || published_at.to_s.strip.empty?
+          errors << {
+            'code' => MISSING_REQUIRED_FIELD,
+            'field' => 'publishedAt',
+            'message' => 'publishedAt date is required.'
+          }
+        elsif !Utils::DateHelper.valid_calendar_date?(published_at.to_s.strip)
+          errors << {
+            'code' => INVALID_REQUEST,
+            'field' => 'publishedAt',
+            'message' => 'publishedAt must be a valid calendar date in YYYY-MM-DD format.'
+          }
+        end
+
+        # 5. Topic validation
+        if topic.nil? || topic.to_s.strip.empty?
+          errors << {
+            'code' => MISSING_REQUIRED_FIELD,
+            'field' => 'topic',
+            'message' => 'Topic is required.'
+          }
+        end
+
+        # 6. Summary validation
+        if summary.nil? || summary.to_s.strip.empty?
+          errors << {
+            'code' => MISSING_REQUIRED_FIELD,
+            'field' => 'summary',
+            'message' => 'Summary is required.'
+          }
+        end
+
+        # 7. Tags validation (optional)
+        if !tags.nil? && !tags.is_a?(Array)
+          errors << {
+            'code' => INVALID_REQUEST,
+            'field' => 'tags',
+            'message' => 'Tags must be an array of strings.'
+          }
+        end
+
+        # 8. minWordCount validation (optional)
+        if !min_word_count.nil? && (!min_word_count.is_a?(Numeric) || min_word_count < 1)
+          errors << {
+            'code' => INVALID_REQUEST,
+            'field' => 'minWordCount',
+            'message' => 'minWordCount must be a positive integer.'
+          }
+        end
+
+        # 9. referenceDate validation (optional)
+        if !reference_date.nil? && !Utils::DateHelper.valid_calendar_date?(reference_date.to_s.strip)
+          errors << {
+            'code' => INVALID_REQUEST,
+            'field' => 'referenceDate',
+            'message' => 'referenceDate must be a valid calendar date in YYYY-MM-DD format.'
+          }
+        end
+
+        if errors.empty?
+          {
+            valid: true,
+            sanitized: {
+              'platform' => platform.to_s.downcase.strip,
+              'url' => url.to_s.strip,
+              'username' => username.to_s.strip,
+              'publishedAt' => published_at.to_s.strip,
+              'topic' => topic.to_s.strip,
+              'summary' => summary.to_s.strip,
+              'tags' => tags,
+              'minWordCount' => min_word_count ? min_word_count.to_i : 500,
+              'referenceDate' => reference_date ? reference_date.to_s.strip : nil
+            }
+          }
+        else
+          { valid: false, errors: errors }
+        end
+      end
+
+      # Retrieves adapter for the requested platform
+      def get_adapter(platform)
+        plat = platform.to_s.downcase.strip
+        adapter = @adapters[plat]
+        unless adapter
+          raise ValidationError.new(INVALID_PLATFORM, "Unsupported platform: '#{platform}'.", 'platform')
+        end
+        adapter
+      end
+
+      # Performs end-to-end verification of blog metadata
+      # Returns JSON-compatible verification result
+      def verify(params)
+        validation = validate_input(params)
+        unless validation[:valid]
+          return {
+            'success' => false,
+            'status' => 'error',
+            'errors' => validation[:errors]
+          }
+        end
+
+        request_data = validation[:sanitized]
+        platform = request_data['platform']
+        url = request_data['url']
+
+        adapter = get_adapter(platform)
+
+        # Validate URL format and platform host
+        begin
+          Utils::UrlSecurity.validate_article_url(url, platform)
+        rescue ValidationError => e
+          return {
+            'success' => false,
+            'status' => 'error',
+            'errors' => [
+              {
+                'code' => e.error_code,
+                'field' => e.field || 'url',
+                'message' => e.message
+              }
+            ]
+          }
+        rescue SSRFError => e
+          return {
+            'success' => false,
+            'status' => 'error',
+            'errors' => [
+              {
+                'code' => e.error_code,
+                'field' => 'url',
+                'message' => e.message
+              }
+            ]
+          }
+        end
+
+        metadata = nil
+        begin
+          metadata = adapter.get_article_metadata(url)
+        rescue UpstreamError => e
+          return @validation_service.build_source_failure_response(request_data, e)
+        rescue SSRFError => e
+          return {
+            'success' => false,
+            'status' => 'error',
+            'errors' => [
+              {
+                'code' => e.error_code,
+                'field' => 'url',
+                'message' => e.message
+              }
+            ]
+          }
+        rescue StandardError => e
+          return {
+            'success' => false,
+            'status' => 'error',
+            'errors' => [
+              {
+                'code' => INTERNAL_ERROR,
+                'field' => nil,
+                'message' => "Internal verification error: #{e.message}"
+              }
+            ]
+          }
+        end
+
+        @validation_service.evaluate(request_data, metadata)
+      end
+
+      # Same as verify, but raises exceptions on input or network failures
+      def verify!(params)
+        result = verify(params)
+        if result['status'] == 'error' && result['errors']
+          first_err = result['errors'].first
+          raise ValidationError.new(first_err['code'], first_err['message'], first_err['field'])
+        end
+        result
+      end
+    end
+  end
+end

data/lib/blog_verification/utils/date_helper.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'time'
+
+module BlogVerification
+  module Utils
+    module DateHelper
+      DATE_REGEX = /\A\d{4}-\d{2}-\d{2}\z/.freeze
+
+      class << self
+        # Validates that a string is strictly in YYYY-MM-DD format and represents a valid calendar day
+        def valid_calendar_date?(str)
+          return false unless str.is_a?(String)
+          return false unless str.match?(DATE_REGEX)
+
+          parts = str.split('-').map(&:to_i)
+          year, month, day = parts[0], parts[1], parts[2]
+
+          return false if year < 1000 || year > 9999
+          return false if month < 1 || month > 12
+
+          days_in_month = days_in_month_for(year, month)
+          day >= 1 && day <= days_in_month
+        end
+
+        def days_in_month_for(year, month)
+          case month
+          when 1, 3, 5, 7, 8, 10, 12 then 31
+          when 4, 6, 9, 11 then 30
+          when 2
+            leap_year?(year) ? 29 : 28
+          else
+            0
+          end
+        end
+
+        def leap_year?(year)
+          (year % 4).zero? && ((year % 100) != 0 || (year % 400).zero?)
+        end
+
+        # Normalizes any date input into a YYYY-MM-DD UTC calendar date string
+        def normalize_utc_date(date_input)
+          return nil if date_input.nil?
+
+          if date_input.is_a?(String)
+            # If already YYYY-MM-DD and valid, return as is
+            return date_input if valid_calendar_date?(date_input)
+
+            # Try parsing ISO 8601 or RFC timestamps
+            begin
+              parsed_time = Time.parse(date_input).utc
+              return parsed_time.strftime('%Y-%m-%d')
+            rescue ArgumentError
+              return nil
+            end
+          elsif date_input.is_a?(Time)
+            date_input.utc.strftime('%Y-%m-%d')
+          elsif date_input.is_a?(Date)
+            date_input.strftime('%Y-%m-%d')
+          elsif date_input.is_a?(Numeric)
+            # Handle milliseconds vs seconds
+            sec = date_input < 1e11 ? date_input : (date_input / 1000.0)
+            Time.at(sec).utc.strftime('%Y-%m-%d')
+          end
+        end
+
+        # Compares expected YYYY-MM-DD calendar date with actual date input
+        def compare_calendar_dates(expected_date, actual_date_input)
+          normalized_actual = normalize_utc_date(actual_date_input)
+          return { match: false, normalized_actual: nil } if normalized_actual.nil?
+
+          {
+            match: expected_date == normalized_actual,
+            normalized_actual: normalized_actual
+          }
+        end
+
+        # Returns quarter details for any date or timestamp in UTC
+        # Schedule:
+        # - Quarter 1: 1st April to June (months 4, 5, 6)
+        # - Quarter 2: 1st July to September (months 7, 8, 9)
+        # - Quarter 3: 1st October to December (months 10, 11, 12)
+        # - Quarter 4: 1st January to March (months 1, 2, 3)
+        def get_quarter_info(date_input)
+          return nil if date_input.nil?
+
+          parsed_time = nil
+          if date_input.is_a?(Time)
+            parsed_time = date_input.utc
+          elsif date_input.is_a?(Date)
+            parsed_time = Time.utc(date_input.year, date_input.month, date_input.day)
+          elsif date_input.is_a?(String)
+            if valid_calendar_date?(date_input)
+              parts = date_input.split('-').map(&:to_i)
+              parsed_time = Time.utc(parts[0], parts[1], parts[2])
+            else
+              begin
+                parsed_time = Time.parse(date_input).utc
+              rescue ArgumentError
+                return nil
+              end
+            end
+          elsif date_input.is_a?(Numeric)
+            sec = date_input < 1e11 ? date_input : (date_input / 1000.0)
+            parsed_time = Time.at(sec).utc
+          else
+            return nil
+          end
+
+          y = parsed_time.year
+          m = parsed_time.month
+
+          case m
+          when 4..6
+            q_num = 1
+            q_name = 'April - June'
+            s_date = format('%04d-04-01', y)
+            e_date = format('%04d-06-30', y)
+          when 7..9
+            q_num = 2
+            q_name = 'July - September'
+            s_date = format('%04d-07-01', y)
+            e_date = format('%04d-09-30', y)
+          when 10..12
+            q_num = 3
+            q_name = 'October - December'
+            s_date = format('%04d-10-01', y)
+            e_date = format('%04d-12-31', y)
+          when 1..3
+            q_num = 4
+            q_name = 'January - March'
+            s_date = format('%04d-01-01', y)
+            e_date = format('%04d-03-31', y)
+          end
+
+          {
+            quarter_number: q_num,
+            quarter_name: q_name,
+            year: y,
+            label: "#{q_name} #{y}",
+            start_date: s_date,
+            end_date: e_date
+          }
+        end
+
+        # Verifies whether blog creation date falls in the current quarter
+        def date_in_current_quarter?(blog_date, reference_date = nil)
+          blog_quarter = get_quarter_info(blog_date)
+          current_quarter = get_quarter_info(reference_date || Time.now.utc)
+
+          return { in_current_quarter: false, blog_quarter: nil, current_quarter: current_quarter } if blog_quarter.nil?
+          return { in_current_quarter: false, blog_quarter: blog_quarter, current_quarter: nil } if current_quarter.nil?
+
+          in_current = (blog_quarter[:quarter_number] == current_quarter[:quarter_number]) &&
+                       (blog_quarter[:year] == current_quarter[:year])
+
+          {
+            in_current_quarter: in_current,
+            blog_quarter: blog_quarter,
+            current_quarter: current_quarter
+          }
+        end
+      end
+    end
+  end
+end

data/lib/blog_verification/utils/normalizer.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'cgi'
+require 'set'
+
+module BlogVerification
+  module Utils
+    module Normalizer
+      class << self
+        # Normalizes a username:
+        # - Trims whitespace
+        # - Removes leading '@' if present
+        # - Lowercases for case-insensitive comparison
+        def normalize_username(username)
+          return '' unless username.is_a?(String)
+
+          cleaned = username.strip
+          cleaned = cleaned[1..-1].strip if cleaned.start_with?('@')
+          cleaned.downcase
+        end
+
+        # Normalizes an array of tags:
+        # - Trims whitespace
+        # - Lowercases
+        # - Removes duplicates
+        # - Filters out empty strings
+        # - Sorts for deterministic representation
+        def normalize_tags(tags)
+          return [] unless tags.is_a?(Array)
+
+          tags.map do |tag|
+            tag.is_a?(String) ? tag.strip.downcase : nil
+          end.compact.reject(&:empty?).uniq.sort
+        end
+
+        # Compares two sets of tags for equality, ignoring order
+        def compare_tag_sets(expected_tags, source_tags)
+          norm_expected = normalize_tags(expected_tags)
+          norm_actual = normalize_tags(source_tags)
+
+          if norm_expected.length != norm_actual.length
+            return {
+              match: false,
+              normalized_expected: norm_expected,
+              normalized_actual: norm_actual
+            }
+          end
+
+          match = norm_expected == norm_actual
+          {
+            match: match,
+            normalized_expected: norm_expected,
+            normalized_actual: norm_actual
+          }
+        end
+
+        # Normalizes article summary/description according to FR-08:
+        # - Removes HTML tags
+        # - Decodes HTML entities (e.g. &amp;, &quot;, &#39;, &lt;, &gt;)
+        # - Trims leading and trailing whitespace
+        # - Collapses repeated whitespace
+        # - Case-normalization (lowercase)
+        def normalize_summary(text)
+          return '' unless text.is_a?(String)
+
+          # 1. Remove HTML tags
+          stripped = text.gsub(/<[^>]*>/, ' ')
+          # 2. Decode HTML entities
+          decoded = CGI.unescapeHTML(stripped)
+          # 3. Collapse whitespace and trim
+          collapsed = decoded.gsub(/\s+/, ' ').strip
+          # 4. Lowercase
+          collapsed.downcase
+        end
+
+        # Compares expected summary and actual source description
+        def compare_summaries(expected_summary, source_description)
+          norm_expected = normalize_summary(expected_summary)
+          norm_actual = normalize_summary(source_description)
+
+          match = !norm_expected.empty? && !norm_actual.empty? && (norm_expected == norm_actual)
+          {
+            match: match,
+            normalized_expected: norm_expected,
+            normalized_actual: norm_actual
+          }
+        end
+
+        # Calculates the number of words in an article or text.
+        # - Strips HTML tags
+        # - Decodes HTML entities
+        # - Splits on whitespace and counts non-empty word tokens
+        def count_words(text)
+          return 0 unless text.is_a?(String)
+
+          stripped = text.gsub(/<[^>]*>/, ' ')
+          decoded = CGI.unescapeHTML(stripped)
+          words = decoded.strip.split(/\s+/).reject(&:empty?)
+          words.length
+        end
+      end
+    end
+  end
+end