better_seo 0.14.0 → 1.0.0.1

data/lib/better_seo/sitemap/url_entry.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "uri"
+require "date"
+
+module BetterSeo
+  module Sitemap
+    class UrlEntry
+      VALID_CHANGEFREQ = %w[always hourly daily weekly monthly yearly never].freeze
+
+      attr_reader :loc, :lastmod, :changefreq, :priority, :alternates, :images, :videos
+
+      def initialize(loc, lastmod: nil, changefreq: "weekly", priority: 0.5)
+        @loc = loc
+        @lastmod = format_date(lastmod) if lastmod
+        @changefreq = changefreq
+        @priority = priority
+        @alternates = []
+        @images = []
+        @videos = []
+      end
+
+      def lastmod=(value)
+        @lastmod = format_date(value)
+      end
+
+      def changefreq=(value)
+        unless VALID_CHANGEFREQ.include?(value)
+          raise ValidationError, "Invalid changefreq: #{value}. Must be one of: #{VALID_CHANGEFREQ.join(", ")}"
+        end
+        @changefreq = value
+      end
+
+      def priority=(value)
+        unless value.between?(0.0, 1.0)
+          raise ValidationError, "Priority must be between 0.0 and 1.0"
+        end
+        @priority = value
+      end
+
+      # Add alternate language version (hreflang)
+      def add_alternate(href, hreflang:)
+        @alternates << { href: href, hreflang: hreflang }
+        self
+      end
+
+      # Add image
+      def add_image(loc, title: nil, caption: nil)
+        image = { loc: loc }
+        image[:title] = title if title
+        image[:caption] = caption if caption
+        @images << image
+        self
+      end
+
+      # Add video
+      def add_video(thumbnail_loc:, title:, description:, content_loc:, duration: nil)
+        video = {
+          thumbnail_loc: thumbnail_loc,
+          title: title,
+          description: description,
+          content_loc: content_loc
+        }
+        video[:duration] = duration if duration
+        @videos << video
+        self
+      end
+
+      def to_xml
+        xml = []
+        xml << "  <url>"
+        xml << "    <loc>#{escape_xml(@loc)}</loc>"
+        xml << "    <lastmod>#{@lastmod}</lastmod>" if @lastmod
+        xml << "    <changefreq>#{@changefreq}</changefreq>"
+        xml << "    <priority>#{@priority}</priority>"
+
+        # Add images
+        @images.each do |image|
+          xml << "    <image:image>"
+          xml << "      <image:loc>#{escape_xml(image[:loc])}</image:loc>"
+          xml << "      <image:title>#{escape_xml(image[:title])}</image:title>" if image[:title]
+          xml << "      <image:caption>#{escape_xml(image[:caption])}</image:caption>" if image[:caption]
+          xml << "    </image:image>"
+        end
+
+        # Add videos
+        @videos.each do |video|
+          xml << "    <video:video>"
+          xml << "      <video:thumbnail_loc>#{escape_xml(video[:thumbnail_loc])}</video:thumbnail_loc>"
+          xml << "      <video:title>#{escape_xml(video[:title])}</video:title>"
+          xml << "      <video:description>#{escape_xml(video[:description])}</video:description>"
+          xml << "      <video:content_loc>#{escape_xml(video[:content_loc])}</video:content_loc>"
+          xml << "      <video:duration>#{video[:duration]}</video:duration>" if video[:duration]
+          xml << "    </video:video>"
+        end
+
+        # Add hreflang alternates
+        @alternates.each do |alternate|
+          xml << "    <xhtml:link rel=\"alternate\" hreflang=\"#{alternate[:hreflang]}\" href=\"#{escape_xml(alternate[:href])}\" />"
+        end
+
+        xml << "  </url>"
+        xml.join("\n")
+      end
+
+      def to_h
+        hash = {
+          loc: @loc,
+          changefreq: @changefreq,
+          priority: @priority
+        }
+        hash[:lastmod] = @lastmod if @lastmod
+        hash[:alternates] = @alternates if @alternates.any?
+        hash
+      end
+
+      def validate!
+        raise ValidationError, "Location is required" if @loc.nil? || @loc.empty?
+
+        begin
+          uri = URI.parse(@loc)
+          unless uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
+            raise ValidationError, "Invalid URL format: #{@loc}"
+          end
+        rescue URI::InvalidURIError
+          raise ValidationError, "Invalid URL format: #{@loc}"
+        end
+
+        true
+      end
+
+      private
+
+      def format_date(value)
+        case value
+        when String
+          value
+        when Date
+          value.strftime("%Y-%m-%d")
+        when Time, DateTime
+          value.strftime("%Y-%m-%d")
+        else
+          value.to_s
+        end
+      end
+
+      def escape_xml(text)
+        text.to_s
+          .gsub("&", "&amp;")
+          .gsub("<", "&lt;")
+          .gsub(">", "&gt;")
+          .gsub('"', "&quot;")
+          .gsub("'", "&apos;")
+      end
+    end
+  end
+end

data/lib/better_seo/structured_data/article.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module BetterSeo
+  module StructuredData
+    class Article < Base
+      def initialize(**properties)
+        super("Article", **properties)
+      end
+
+      def headline(value)
+        set(:headline, value)
+      end
+
+      def description(value)
+        set(:description, value)
+      end
+
+      def image(value)
+        set(:image, value)
+      end
+
+      def author(value)
+        set(:author, value)
+      end
+
+      def publisher(value)
+        set(:publisher, value)
+      end
+
+      def date_published(value)
+        set(:datePublished, value)
+      end
+
+      def date_modified(value)
+        set(:dateModified, value)
+      end
+
+      def url(value)
+        set(:url, value)
+      end
+
+      def word_count(value)
+        set(:wordCount, value)
+      end
+
+      def keywords(value)
+        set(:keywords, value)
+      end
+
+      def article_section(value)
+        set(:articleSection, value)
+      end
+    end
+  end
+end

data/lib/better_seo/structured_data/base.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "json"
+
+module BetterSeo
+  module StructuredData
+    class Base
+      attr_reader :type, :properties
+
+      def initialize(type, **properties)
+        @type = type
+        @properties = {}
+        properties.each { |key, value| set(key, value) }
+      end
+
+      def set(key, value)
+        @properties[key] = value unless value.nil?
+        self
+      end
+
+      def get(key)
+        @properties[key]
+      end
+
+      def to_h
+        hash = {
+          "@context" => "https://schema.org",
+          "@type" => @type
+        }
+
+        @properties.each do |key, value|
+          hash[key.to_s] = convert_value(value)
+        end
+
+        hash
+      end
+
+      def to_json(*args)
+        JSON.pretty_generate(to_h)
+      end
+
+      def to_script_tag
+        <<~HTML.strip
+          <script type="application/ld+json">
+          #{to_json}
+          </script>
+        HTML
+      end
+
+      def valid?
+        !@type.nil? && !@type.to_s.empty?
+      end
+
+      def validate!
+        raise ValidationError, "@type is required for structured data" unless valid?
+        true
+      end
+
+      private
+
+      def convert_value(value)
+        case value
+        when Base
+          value.to_h
+        when Array
+          value.map { |v| convert_value(v) }
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/better_seo/structured_data/breadcrumb_list.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module BetterSeo
+  module StructuredData
+    class BreadcrumbList < Base
+      attr_reader :items
+
+      def initialize(**properties)
+        super("BreadcrumbList", **properties)
+        @items = []
+      end
+
+      def add_item(name:, url:, position: nil)
+        position ||= @items.size + 1
+        @items << { name: name, url: url, position: position }
+        self
+      end
+
+      def add_items(items_array)
+        items_array.each do |item|
+          add_item(
+            name: item[:name],
+            url: item[:url],
+            position: item[:position]
+          )
+        end
+        self
+      end
+
+      def clear
+        @items = []
+        self
+      end
+
+      def to_h
+        hash = super
+        hash["itemListElement"] = @items.map do |item|
+          {
+            "@type" => "ListItem",
+            "position" => item[:position],
+            "name" => item[:name],
+            "item" => item[:url]
+          }
+        end
+        hash
+      end
+    end
+  end
+end

data/lib/better_seo/structured_data/event.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module BetterSeo
+  module StructuredData
+    class Event < Base
+      EVENT_STATUS_MAPPING = {
+        "EventScheduled" => "https://schema.org/EventScheduled",
+        "EventCancelled" => "https://schema.org/EventCancelled",
+        "EventPostponed" => "https://schema.org/EventPostponed",
+        "EventRescheduled" => "https://schema.org/EventRescheduled"
+      }.freeze
+
+      ATTENDANCE_MODE_MAPPING = {
+        "OfflineEventAttendanceMode" => "https://schema.org/OfflineEventAttendanceMode",
+        "OnlineEventAttendanceMode" => "https://schema.org/OnlineEventAttendanceMode",
+        "MixedEventAttendanceMode" => "https://schema.org/MixedEventAttendanceMode"
+      }.freeze
+
+      AVAILABILITY_MAPPING = {
+        "InStock" => "https://schema.org/InStock",
+        "SoldOut" => "https://schema.org/SoldOut",
+        "PreOrder" => "https://schema.org/PreOrder"
+      }.freeze
+
+      def initialize(**properties)
+        super("Event", **properties)
+      end
+
+      # Basic properties
+      def name(value)
+        set(:name, value)
+      end
+
+      def description(value)
+        set(:description, value)
+      end
+
+      def url(value)
+        set(:url, value)
+      end
+
+      def image(value)
+        set(:image, value)
+      end
+
+      # Date and time
+      def start_date(value)
+        formatted_value = format_date(value)
+        set(:startDate, formatted_value)
+      end
+
+      def end_date(value)
+        formatted_value = format_date(value)
+        set(:endDate, formatted_value)
+      end
+
+      # Event status
+      def event_status(value)
+        status_value = if value.start_with?("https://schema.org/")
+                         value
+                       else
+                         EVENT_STATUS_MAPPING[value] || value
+                       end
+        set(:eventStatus, status_value)
+      end
+
+      # Event attendance mode
+      def event_attendance_mode(value)
+        mode_value = if value.start_with?("https://schema.org/")
+                       value
+                     else
+                       ATTENDANCE_MODE_MAPPING[value] || value
+                     end
+        set(:eventAttendanceMode, mode_value)
+      end
+
+      # Location (Place or VirtualLocation)
+      def location(type: nil, name: nil, address: nil, url: nil, **other_properties)
+        location_hash = {}
+
+        location_hash["@type"] = type if type
+        location_hash["name"] = name if name
+        location_hash["url"] = url if url
+
+        if address
+          location_hash["address"] = build_address(address)
+        end
+
+        other_properties.each do |key, value|
+          location_hash[key.to_s] = value
+        end
+
+        set(:location, location_hash)
+      end
+
+      # Organizer (Organization or Person)
+      def organizer(value)
+        organizer_value = if value.is_a?(Base)
+                            value
+                          elsif value.is_a?(Hash)
+                            build_organizer(value)
+                          else
+                            value
+                          end
+
+        set(:organizer, organizer_value)
+      end
+
+      # Offers
+      def offers(value)
+        if value.is_a?(Array)
+          set(:offers, value.map { |v| build_offer(v) })
+        elsif value.is_a?(Hash)
+          set(:offers, build_offer(value))
+        else
+          set(:offers, value)
+        end
+      end
+
+      # Performer
+      def performer(value)
+        if value.is_a?(Array)
+          set(:performer, value.map { |v| build_performer(v) })
+        elsif value.is_a?(Hash)
+          set(:performer, build_performer(value))
+        else
+          set(:performer, value)
+        end
+      end
+
+      private
+
+      def format_date(value)
+        case value
+        when Date
+          value.to_s
+        when Time, DateTime
+          value.iso8601
+        else
+          value
+        end
+      end
+
+      def build_address(address)
+        return address unless address.is_a?(Hash)
+
+        address_hash = {
+          "@type" => "PostalAddress"
+        }
+
+        address_hash["streetAddress"] = address[:street] if address[:street]
+        address_hash["addressLocality"] = address[:city] if address[:city]
+        address_hash["addressRegion"] = address[:region] if address[:region]
+        address_hash["postalCode"] = address[:postal_code] if address[:postal_code]
+        address_hash["addressCountry"] = address[:country] if address[:country]
+
+        address_hash
+      end
+
+      def build_organizer(hash)
+        organizer = {
+          "@type" => hash[:type] || "Organization"
+        }
+
+        organizer["name"] = hash[:name] if hash[:name]
+        organizer["url"] = hash[:url] if hash[:url]
+        organizer["email"] = hash[:email] if hash[:email]
+
+        organizer
+      end
+
+      def build_offer(hash)
+        offer = {
+          "@type" => "Offer"
+        }
+
+        offer["name"] = hash[:name] if hash[:name]
+        offer["price"] = hash[:price] if hash[:price]
+        offer["priceCurrency"] = hash[:price_currency] if hash[:price_currency]
+        offer["url"] = hash[:url] if hash[:url]
+        offer["validFrom"] = hash[:valid_from] if hash[:valid_from]
+        offer["validThrough"] = hash[:valid_through] if hash[:valid_through]
+
+        if hash[:availability]
+          offer["availability"] = if hash[:availability].start_with?("https://")
+                                    hash[:availability]
+                                  else
+                                    AVAILABILITY_MAPPING[hash[:availability]] || hash[:availability]
+                                  end
+        end
+
+        offer
+      end
+
+      def build_performer(hash)
+        performer = {
+          "@type" => hash[:type] || "Person"
+        }
+
+        performer["name"] = hash[:name] if hash[:name]
+        performer["url"] = hash[:url] if hash[:url]
+
+        performer
+      end
+    end
+  end
+end

data/lib/better_seo/structured_data/faq_page.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module BetterSeo
+  module StructuredData
+    class FAQPage < Base
+      attr_reader :questions
+
+      def initialize(**properties)
+        super("FAQPage", **properties)
+        @questions = []
+      end
+
+      # Add a single question
+      def add_question(question:, answer:)
+        @questions << { question: question, answer: answer }
+        self
+      end
+
+      # Add multiple questions from an array
+      def add_questions(questions_array)
+        questions_array.each do |q|
+          add_question(question: q[:question], answer: q[:answer])
+        end
+        self
+      end
+
+      # Clear all questions
+      def clear
+        @questions = []
+        @properties.delete(:mainEntity)
+        self
+      end
+
+      # Override to_h to include mainEntity
+      def to_h
+        hash = super
+
+        if @questions.any?
+          hash["mainEntity"] = @questions.map do |q|
+            {
+              "@type" => "Question",
+              "name" => q[:question],
+              "acceptedAnswer" => {
+                "@type" => "Answer",
+                "text" => q[:answer]
+              }
+            }
+          end
+        end
+
+        hash
+      end
+    end
+  end
+end

data/lib/better_seo/structured_data/generator.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module BetterSeo
+  module StructuredData
+    class Generator
+      class << self
+        def generate_script_tags(structured_data_array)
+          return "" if structured_data_array.empty?
+
+          structured_data_array.map(&:to_script_tag).join("\n\n")
+        end
+
+        def organization(**properties, &block)
+          org = Organization.new(**properties)
+          yield(org) if block_given?
+          org
+        end
+
+        def article(**properties, &block)
+          article = Article.new(**properties)
+          yield(article) if block_given?
+          article
+        end
+
+        def person(**properties, &block)
+          person = Person.new(**properties)
+          yield(person) if block_given?
+          person
+        end
+
+        def product(**properties, &block)
+          product = Product.new(**properties)
+          yield(product) if block_given?
+          product
+        end
+
+        def breadcrumb_list(**properties, &block)
+          breadcrumb = BreadcrumbList.new(**properties)
+          yield(breadcrumb) if block_given?
+          breadcrumb
+        end
+
+        def local_business(**properties, &block)
+          business = LocalBusiness.new(**properties)
+          yield(business) if block_given?
+          business
+        end
+
+        def event(**properties, &block)
+          event = Event.new(**properties)
+          yield(event) if block_given?
+          event
+        end
+
+        def faq_page(**properties, &block)
+          faq = FAQPage.new(**properties)
+          yield(faq) if block_given?
+          faq
+        end
+
+        def how_to(**properties, &block)
+          how_to = HowTo.new(**properties)
+          yield(how_to) if block_given?
+          how_to
+        end
+
+        def recipe(**properties, &block)
+          recipe = Recipe.new(**properties)
+          yield(recipe) if block_given?
+          recipe
+        end
+      end
+    end
+  end
+end