seo_geo 0.1.0

data/lib/seo_geo/markdown/path_suffix.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module SeoGeo
+  module Markdown
+    # Rack middleware that makes +/<path>.md+ work for every route: it strips the suffix, maps
+    # +/index.md+ to +/+ and marks the request as a Markdown request (+Accept: text/markdown+ and
+    # +env["seo_geo.markdown"]+). Actions that include {SeoGeo::Markdownable} answer in Markdown;
+    # every other action gets a plain 406 — whether Rails raised +UnknownFormat+ or the action
+    # rendered HTML anyway — so a +.md+ URL never 500s or serves HTML.
+    #
+    # Appended to the middleware stack by the engine (after ActionDispatch::Static), so real
+    # +public/*.md+ files still win.
+    # llms.txt links pages as +/<path>.md+ and the root as +/index.md+.
+    class PathSuffix
+      ENV_KEY = "seo_geo.markdown"
+      NOT_ACCEPTABLE = [406, { "content-type" => "text/plain; charset=utf-8", "vary" => "Accept" },
+                        ["Not Acceptable: no Markdown version of this page\n"]].freeze
+      private_constant :NOT_ACCEPTABLE
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        path = env["PATH_INFO"].to_s
+        if SeoGeo.config.markdown.suffix_urls? && path.end_with?(".md") && %w[GET HEAD].include?(env["REQUEST_METHOD"])
+          env["PATH_INFO"] = self.class.html_path(path)
+          env["HTTP_ACCEPT"] = "text/markdown"
+          env[ENV_KEY] = true
+          return markdown_call(env)
+        end
+        @app.call(env)
+      end
+
+      # @param path [String] e.g. "/docs/intro.md", "/index.md", "/docs/index.md"
+      # @return [String] "/docs/intro", "/", "/docs/"
+      def self.html_path(path)
+        stripped = path.delete_suffix(".md")
+        return stripped.delete_suffix("index") if stripped.end_with?("/index")
+
+        stripped.empty? ? "/" : stripped
+      end
+
+      private
+
+      def markdown_call(env)
+        status, headers, body = @app.call(env)
+        return [status, headers, body] unless status.to_i == 200 && !markdown_response?(headers)
+
+        body.close if body.respond_to?(:close)
+        not_acceptable
+      rescue ActionController::UnknownFormat
+        not_acceptable
+      rescue ActionView::MissingTemplate => e
+        # An explicit +render :show+ in a non-markdownable action looks up an +.md+ template.
+        raise unless e.message.match?(/formats.{0,4}\[:md\]/)
+
+        not_acceptable
+      end
+
+      def markdown_response?(headers)
+        type = headers.find { |name, _| name.to_s.casecmp?("content-type") }&.last
+        type.to_s.start_with?("text/markdown")
+      end
+
+      def not_acceptable
+        status, headers, body = NOT_ACCEPTABLE
+        [status, headers.dup, body.dup]
+      end
+    end
+  end
+end

data/lib/seo_geo/markdownable.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require_relative "markdown/negotiation"
+require_relative "markdown/document"
+require_relative "markdown/path_suffix"
+
+module SeoGeo
+  # Serves a Markdown version of HTML actions to agents (+Accept: text/markdown+ or a +.md+ URL).
+  #
+  # The action runs and renders HTML as usual; an +after_action+ then converts the main content to
+  # Markdown, prepends YAML frontmatter and appends JSON-LD in a +json+ fence. Responses of
+  # markdownable actions always carry +Vary: Accept+, HTML or not, so caches keep the two apart.
+  #
+  # @example Every action of a controller
+  #   class PagesController < ApplicationController
+  #     include SeoGeo::Markdownable
+  #   end
+  #
+  # @example Selected actions, an Inertia page backed by page copy, a custom selector
+  #   class LandingController < ApplicationController
+  #     include SeoGeo::Markdownable
+  #     seo_geo_markdown only: :show, page: :home, selector: "#content"
+  #   end
+  #
+  # @example .md URLs need no routes: {SeoGeo::Markdown::PathSuffix} maps /articles/1.md to /articles/1
+  #   and /index.md to /, so every markdownable action answers both forms.
+  module Markdownable
+    extend ActiveSupport::Concern
+
+    # Header that tells an origin-side CDN converter (or a test) the response already is Markdown.
+    CONTENT_TYPE = "text/markdown; charset=utf-8"
+
+    included do
+      class_attribute :seo_geo_markdown_options, instance_writer: false, default: {}
+      before_action :seo_geo_prepare_markdown, if: :seo_geo_markdownable_action?
+      after_action :seo_geo_finish_markdown, if: :seo_geo_markdownable_action?
+    end
+
+    class_methods do
+      # @param only [Symbol, Array<Symbol>, nil] restrict to these actions
+      # @param except [Symbol, Array<Symbol>, nil] every action but these
+      # @param page [Symbol, #call, nil] page key (or +(controller) -> key+) whose copy is used when the
+      #   HTML has no main content, e.g. an Inertia mount point
+      # @param selector [String, nil] main-content selector overriding +config.markdown.selector+
+      # @return [void]
+      def seo_geo_markdown(only: nil, except: nil, page: nil, selector: nil)
+        self.seo_geo_markdown_options = {
+          only: only && Array(only).map(&:to_s), except: except && Array(except).map(&:to_s),
+          page: page, selector: selector
+        }
+      end
+    end
+
+    # @return [Boolean] true when Markdown is enabled and this action is covered by +seo_geo_markdown only:/except:+
+    def seo_geo_markdown_available?
+      SeoGeo.config.markdown.enabled && seo_geo_markdownable_action?
+    end
+
+    private
+
+    def seo_geo_markdownable_action?
+      options = seo_geo_markdown_options
+      return false if options[:only] && !options[:only].include?(action_name)
+      return false if options[:except]&.include?(action_name)
+
+      true
+    end
+
+    def seo_geo_markdown_requested?
+      return false unless SeoGeo.config.markdown.enabled
+
+      request.env[SeoGeo::Markdown::PathSuffix::ENV_KEY] || params[:format].to_s == "md" ||
+        SeoGeo::Markdown::Negotiation.markdown?(request.headers["Accept"])
+    end
+
+    # Render HTML whatever was asked for; the after_action converts it. When Rails picked :md from an
+    # Accept header the negotiation turned down (e.g. +text/markdown;q=0+), HTML is the fallback.
+    def seo_geo_prepare_markdown
+      @seo_geo_markdown = seo_geo_markdown_requested?
+      request.format = :html if @seo_geo_markdown || request.format&.symbol == :md
+    end
+
+    def seo_geo_finish_markdown
+      seo_geo_append_vary("Accept")
+      return unless @seo_geo_markdown && response.status == 200 && response.media_type.to_s == "text/html"
+
+      document = SeoGeo::Markdown::Document.new(
+        response.body, config: SeoGeo.config, url: seo_geo_html_url, page: seo_geo_markdown_page,
+                       selector: seo_geo_markdown_options[:selector]
+      )
+      seo_geo_merge_robots_header(document.robots)
+      response.body = document.to_s
+      response.headers["Content-Type"] = CONTENT_TYPE
+      seo_geo_content_signal_headers
+    end
+
+    # Carries the HTML's robots metas (global and crawler-specific) over to the Markdown response, merged with
+    # the X-Robots-Tag already set ({SeoGeo::RobotsDirectives}): global directives stay global even when the
+    # header only had scoped ones (+googlebot: noindex+ does not cover other crawlers), and nothing is dropped.
+    # @param directives [SeoGeo::RobotsDirectives]
+    def seo_geo_merge_robots_header(directives)
+      existing = SeoGeo::RobotsDirectives.parse_header(response.headers["X-Robots-Tag"])
+      merged = existing.merge(directives.restrictive)
+      return if merged == existing
+
+      response.headers["X-Robots-Tag"] = merged.to_header
+    end
+
+    def seo_geo_append_vary(value)
+      current = response.headers["Vary"].to_s.split(",").map(&:strip).reject(&:empty?)
+      return if current.any? { |name| name.casecmp?(value) }
+
+      response.headers["Vary"] = (current + [value]).join(", ")
+    end
+
+    def seo_geo_content_signal_headers
+      config = SeoGeo.config
+      return unless config.markdown.content_signal_header
+
+      response.headers["Content-Signal"] = config.content_signal_value
+      usage = config.content_usage_value
+      response.headers["Content-Usage"] = usage if usage
+    end
+
+    # The HTML URL this Markdown represents (".md" removed), for the canonical fallback.
+    def seo_geo_html_url
+      request.url.sub(/\.md(?=\?|\z)/, "")
+    end
+
+    def seo_geo_markdown_page
+      key = seo_geo_markdown_options[:page]
+      key = key.call(self) if key.respond_to?(:call)
+      return nil if key.nil?
+
+      SeoGeo.page(key)
+    rescue KeyError
+      nil
+    end
+  end
+end

data/lib/seo_geo/meta.rb

@@ -0,0 +1,382 @@
+# frozen_string_literal: true
+
+require "uri"
+require "erb"
+require "json"
+require "meta-tags"
+
+module SeoGeo
+  # Resolves the head tags of one request from the configuration, the controller's +seo(...)+
+  # call and the page copy. Pure Ruby (no view), so the rules are unit-testable:
+  #
+  # - title: +seo title:+ > app +set_meta_tags title:+ > page title > site name, rendered once through
+  #   {Configuration#format_title} (the only title template).
+  # - description: +seo description:+ > page description > site description, truncated by
+  #   {Configuration#truncate_description}.
+  # - canonical: {Configuration#canonical_url} of the request URL (aliases and query folded), or of
+  #   +seo canonical: "/path"+; +seo canonical: false+ drops it. With +locales+, a non-default locale's
+  #   canonical is its own hreflang URL (self-referencing, like the hreflang alternates).
+  # - robots: noindex when the host policy is not indexable (every host outside indexable_environments),
+  #   when +seo noindex: true+, or when +default_noindex+ is on and the controller did not call +seo index: true+.
+  class Meta
+    # Per-request values set by the controller ({SeoGeo::Controller#seo}) or views.
+    State = Struct.new(:title, :description, :image, :noindex, :index, :canonical, :page, :type,
+                       :markdown, :json_ld, keyword_init: true) do
+      def initialize(**)
+        super
+        self.json_ld ||= []
+      end
+    end
+
+    # @return [Configuration]
+    attr_reader :config
+    # @return [State]
+    attr_reader :state
+    # @return [String] the request URL
+    attr_reader :url
+    # @return [Symbol, nil]
+    attr_reader :locale
+
+    # @param config [Configuration]
+    # @param url [String] absolute request URL (+request.url+)
+    # @param locale [Symbol, String, nil] current locale (+I18n.locale+)
+    # @param state [State]
+    # @param app_title [String, nil] title set through meta-tags' +set_meta_tags+ / +title+ helpers
+    # @param markdown_available [Boolean] whether this request's action serves Markdown
+    #   ({SeoGeo::Controller#seo_geo_markdown_available?}); +seo markdown: true+ overrides it
+    def initialize(url:, config: SeoGeo.config, locale: nil, state: State.new, app_title: nil, markdown_available: true)
+      @config = config
+      @url = url.to_s
+      @locale = (locale || config.site.default_locale)&.to_sym
+      @state = state
+      @app_title = app_title
+      @markdown_available = markdown_available
+    end
+
+    # @return [Page, nil]
+    def page
+      return @page if defined?(@page)
+
+      @page = case state.page
+              when nil then nil
+              when Page then state.page
+              else SeoGeo.page(state.page, locale: locale)
+              end
+    end
+
+    # @return [String, nil] title without the site suffix
+    def title
+      [state.title, @app_title, page&.title, config.site.name].find { |value| present?(value) }&.to_s
+    end
+
+    # @return [String, nil] the +<title>+ text
+    def full_title
+      title && config.format_title(title)
+    end
+
+    # @return [String, nil]
+    def description
+      config.truncate_description([state.description, page&.description, config.site.description].find { |value| present?(value) })
+    end
+
+    # @return [String, nil] lower-case request host
+    def host
+      URI.parse(url).host&.downcase
+    rescue URI::InvalidURIError
+      nil
+    end
+
+    # @return [HostPolicy]
+    def host_policy
+      config.host_policy(host.to_s)
+    end
+
+    # @return [Boolean] true outside indexable environments and on non-indexable hosts
+    def environment_noindex?
+      return false if host_policy.indexable
+
+      UndeclaredHost.warn_once(host, config: config)
+      true
+    end
+
+    # @return [Boolean] also true for paths declared noindex ({Configuration#noindex_paths} or sitemap
+    #   +add path, noindex: true+), even when the controller called +seo index: true+
+    def noindex?
+      return true if environment_noindex? || state.noindex == true || declared_noindex?
+
+      config.default_noindex ? !(state.index == true || declared_index?) : false
+    end
+
+    # @return [String, nil] canonical URL with aliases/query folded; nil when disabled
+    def canonical
+      return @canonical if defined?(@canonical)
+
+      @canonical = if state.canonical == false then nil
+                   elsif present?(state.canonical) then config.canonical_url(state.canonical.to_s)
+                   elsif localized? then locale_url(locale, base_canonical)
+                   else base_canonical
+                   end
+    end
+
+    # @return [Array<Hash{Symbol => String}>] +{hreflang:, href:}+ for every locale plus x-default
+    def alternates
+      return [] unless localized? && canonical && state.canonical.nil?
+
+      links = config.locales.map { |name| { hreflang: name.to_s, href: locale_url(name, base_canonical) } }
+      x_default = config.effective_x_default_locale
+      links << { hreflang: "x-default", href: locale_url(x_default, base_canonical) } if x_default
+      links
+    end
+
+    # URL of the Markdown version advertised with +<link rel="alternate" type="text/markdown">+:
+    # +/+ -> +/index.md+, +/docs/a+ -> +/docs/a.md+ (query kept). nil when Markdown is off, the page
+    # is noindex or has no canonical, or the action does not serve Markdown (+seo markdown: true+ forces it).
+    # @return [String, nil]
+    def markdown_url
+      return nil unless config.markdown.suffix_urls? && state.markdown != false && canonical && !noindex?
+      return nil unless state.markdown == true || @markdown_available
+
+      self.class.markdown_url_for(canonical)
+    end
+
+    # @param url [String] absolute URL
+    # @return [String] the +.md+ URL for it
+    def self.markdown_url_for(url)
+      uri = URI.parse(url)
+      path = uri.path.to_s
+      uri.path = path.empty? || path.end_with?("/") ? "#{path.chomp("/")}/index.md" : "#{path}.md"
+      uri.to_s
+    end
+
+    # @return [String, nil] absolute OG image URL (+seo image:+ > page +image+ > og_image.fallback_url)
+    def image_url
+      image = state.image
+      image = image[:url] || image["url"] if image.is_a?(Hash)
+      image ||= page&.extra&.dig(:image)
+      image ||= config.og_image.fallback_url
+      return nil unless present?(image)
+
+      absolute(image.to_s)
+    end
+
+    # @return [Hash] options for meta-tags' renderer (everything except +title+)
+    def tags
+      tags = { description: description, canonical: canonical, alternate: alternate_links }
+      if noindex?
+        tags[:noindex] = true
+        tags[:nofollow] = true if environment_noindex?
+      end
+      tags[:og] = open_graph
+      tags[:twitter] = twitter
+      tags.merge(config.verification.meta_tags.transform_keys(&:to_sym)).compact
+    end
+
+    # @return [JsonLd] WebSite + Organization (when site.name is set), the page's FAQPage, then nodes
+    #   added with +seo json_ld:+ / +seo_geo_json_ld+
+    def json_ld
+      document = JsonLd.new(config: config)
+      if present?(config.site.name)
+        document.website(in_language: locale&.to_s)
+        document.organization
+      end
+      document.add(page.json_ld(url: canonical || "#{document.origin}/", config: config)) if page
+      state.json_ld.each { |node| document.add(node) }
+      document
+    end
+
+    private
+
+    # one declaration drives robots meta, sitemap.xml and llms.txt.
+    def declared_noindex?
+      Publication.declared_noindex?(request_path, config: config)
+    end
+
+    # Under +default_noindex+, a path registered with +index: true+ for this host is indexable (same rule as
+    # sitemap.xml): a static path or a record of a collection added with +match:+.
+    def declared_index?
+      Publication.declared_index?(host.to_s, request_path, config: config)
+    end
+
+    def request_path
+      RobotsPath.path(url)
+    end
+
+    def localized?
+      !config.locales.empty? && config.locales.map(&:to_sym).include?(locale)
+    end
+
+    def base_canonical
+      @base_canonical ||= config.canonical_url(url)
+    end
+
+    def locale_url(name, base)
+      return config.hreflang_url.call(name.to_sym, base) if config.hreflang_url
+      return base if name.to_sym == config.site.default_locale.to_sym
+
+      "#{base}#{base.include?("?") ? "&" : "?"}locale=#{ERB::Util.url_encode(name.to_s)}"
+    end
+
+    def alternate_links
+      links = alternates.map { |link| { href: link[:href], hreflang: link[:hreflang] } }
+      links << { href: markdown_url, type: "text/markdown" } if markdown_url
+      links.empty? ? nil : links
+    end
+
+    def open_graph
+      image = image_url
+      {
+        type: state.type || "website",
+        site_name: config.site.name,
+        title: title,
+        description: description,
+        url: canonical,
+        locale: og_locale,
+        image: image && { _: image, **image_size(image) }.compact
+      }.compact
+    end
+
+    # +og:image:width/height+ only when the size is known: an explicit +seo image: {url:, width:, height:}+, an image
+    # the gem renders (+/og/<key>.png+ on this origin while og_image is enabled => og_image.width x height), or
+    # the fallback image with +og_image.fallback_width/height+. A wrong size is worse than none.
+    def image_size(url)
+      explicit = state.image
+      if explicit.is_a?(Hash)
+        width = explicit[:width] || explicit["width"]
+        height = explicit[:height] || explicit["height"]
+        return { width: width, height: height } if width && height
+      end
+      og = config.og_image
+      return { width: og.width, height: og.height } if og.enabled? && gem_rendered?(url)
+      return { width: og.fallback_width, height: og.fallback_height } if url == og.fallback_url && og.fallback_width && og.fallback_height
+
+      {}
+    end
+
+    OG_IMAGE_PATH = %r{\A/og/[a-zA-Z0-9_-]{1,100}\.png\z} # GET /og/:key.png (OgImage::KEY_FORMAT)
+
+    def gem_rendered?(url)
+      uri = URI.parse(url)
+      URI.parse(absolute("/")).host.to_s.casecmp?(uri.host.to_s) && uri.path.match?(OG_IMAGE_PATH)
+    rescue URI::InvalidURIError
+      false
+    end
+
+    def twitter
+      image = image_url
+      { card: image ? "summary_large_image" : "summary", title: title, description: description, image: image }.compact
+    end
+
+    # Open Graph wants language_TERRITORY: +ko+ => +ko_KR+, +en-GB+ => +en_GB+ ({Configuration#og_locale}).
+    def og_locale
+      config.og_locale(locale)
+    end
+
+    def absolute(value)
+      return value if value.match?(%r{\Ahttps?://}i)
+
+      "#{config.canonical_origin}#{value.start_with?("/") ? "" : "/"}#{value}"
+    end
+
+    def present?(value)
+      !value.nil? && !(value.respond_to?(:empty?) && value.empty?)
+    end
+
+    # View helpers, included into ActionView by the engine (initializer "seo_geo.helpers").
+    module Helper
+      FALLBACK_TIMEOUT_MS = 5000
+
+      # The whole SEO head in one line: +<title>+, description, canonical, robots, hreflang, Markdown
+      # alternate, verification metas, Open Graph/Twitter, JSON-LD and the crawler-fallback snippet.
+      # Values set with meta-tags' +set_meta_tags+ still apply (seo_geo supplies the defaults), except
+      # that the title always goes through +title_template+ and non-indexable environments always get noindex.
+      #
+      # @param page [Symbol, Page, nil] page copy for title/description/FAQ (defaults to +seo page:+)
+      # @param json_ld [Boolean] emit the JSON-LD script
+      # @param fallback [Boolean] emit the crawler-fallback hide/unhide snippet
+      # @return [ActiveSupport::SafeBuffer]
+      def seo_geo_head(page: nil, json_ld: true, fallback: true)
+        meta = seo_geo_meta(page: page)
+        parts = [meta.full_title && content_tag(:title, meta.full_title), seo_geo_render_meta_tags(meta)]
+        parts << seo_geo_json_ld_tag(meta.json_ld) if json_ld && !meta.json_ld.empty?
+        parts << content_for(:seo_geo_json_ld) if content_for?(:seo_geo_json_ld)
+        parts << seo_geo_fallback_snippet if fallback
+        safe_join(parts.compact, "\n")
+      end
+
+      # @param page [Symbol, Page, nil]
+      # @return [Meta] resolved values for the current request (also handy for custom tags)
+      def seo_geo_meta(page: nil)
+        state = respond_to?(:seo_geo_state) ? seo_geo_state : State.new
+        state.page = page if page
+        app_title = respond_to?(:meta_tags) ? meta_tags[:title] : nil
+        app_title = nil if app_title.is_a?(Array)
+        Meta.new(config: SeoGeo.config, url: request.url, locale: seo_geo_locale,
+                 state: state, app_title: app_title,
+                 markdown_available: respond_to?(:seo_geo_markdown_available?) && seo_geo_markdown_available?)
+      end
+
+      # @return [String] value for +<html lang>+: the same locale as +og:locale+ and +WebSite.inLanguage+
+      def seo_geo_html_lang
+        seo_geo_locale.to_s
+      end
+
+      # @return [Symbol] +I18n.locale+ when +config.locales+ lists it, else +site.default_locale+
+      #   ({Configuration#request_locale})
+      def seo_geo_locale
+        SeoGeo.config.request_locale(defined?(I18n) ? I18n.locale : nil)
+      end
+
+      # Adds nodes to this page's JSON-LD graph (rendered by {#seo_geo_head}). Call it from a view;
+      # views render before the layout's head.
+      # @param node [Hash, JsonLd]
+      # @return [nil]
+      def seo_geo_json_ld(node)
+        seo_geo_state.json_ld << node if respond_to?(:seo_geo_state)
+        nil
+      end
+
+      # A +<script type="application/ld+json">+ tag, escaped with +ERB::Util.json_escape+ and carrying
+      # the CSP nonce when one is configured. Use it for extra scripts in +content_for(:seo_geo_json_ld)+.
+      # @param data [Hash, JsonLd]
+      # @return [ActiveSupport::SafeBuffer]
+      def seo_geo_json_ld_tag(data)
+        hash = data.is_a?(JsonLd) ? data.to_h : data
+        json = ERB::Util.json_escape(JSON.generate(hash))
+        content_tag(:script, json.html_safe, type: "application/ld+json", nonce: seo_geo_nonce) # rubocop:disable Rails/OutputSafety
+      end
+
+      private
+
+      def seo_geo_render_meta_tags(meta)
+        collection = respond_to?(:meta_tags) ? meta_tags : MetaTags::MetaTagsCollection.new
+        collection.with_defaults(meta.tags) do
+          collection[:title] = nil
+          collection[:site] = nil
+          if meta.noindex?
+            %i[index follow].each { |key| collection.meta_tags.delete(key) }
+            collection[:noindex] = true
+            collection[:nofollow] = true if meta.environment_noindex?
+          end
+          MetaTags::Renderer.new(collection).render(self)
+        end
+      end
+
+      # Hides [data-seo-fallback] while JavaScript runs; shows it again when the app has not called
+      # window.SeoGeo.mounted() within FALLBACK_TIMEOUT_MS (bundle failed to load).
+      def seo_geo_fallback_snippet
+        script = "(function(w,d){var r=d.documentElement,m=false;r.classList.add(\"seo-geo-js\");" \
+                 "w.SeoGeo=w.SeoGeo||{};w.SeoGeo.mounted=function(){m=true;r.classList.add(\"seo-geo-mounted\")};" \
+                 "setTimeout(function(){if(!m)r.classList.remove(\"seo-geo-js\")},#{FALLBACK_TIMEOUT_MS})})(window,document)"
+        style = ".seo-geo-js [data-seo-fallback]{display:none}" \
+                "[data-seo-fallback]{max-width:720px;margin:0 auto;padding:32px 16px;line-height:1.6;" \
+                "word-break:keep-all;overflow-wrap:break-word}"
+        safe_join([content_tag(:script, script.html_safe, nonce: seo_geo_nonce), # rubocop:disable Rails/OutputSafety
+                   content_tag(:style, style.html_safe, nonce: seo_geo_nonce)], "\n") # rubocop:disable Rails/OutputSafety
+      end
+
+      def seo_geo_nonce
+        respond_to?(:content_security_policy_nonce) ? content_security_policy_nonce : nil
+      end
+    end
+  end
+end

data/lib/seo_geo/model.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module SeoGeo
+  # Model macro that submits a record's public URL to IndexNow after commit.
+  # The engine extends ActiveRecord::Base with it; other ORMs can +extend SeoGeo::Model+ as long as
+  # they provide +after_commit+.
+  #
+  # @example
+  #   class Article < ApplicationRecord
+  #     seo_geo_indexnow on: :publish, url: ->(article) { Rails.application.routes.url_helpers.article_url(article) }
+  #   end
+  module Model
+    EVENTS = %i[create update destroy publish].freeze
+
+    # @param on [Symbol, Array<Symbol>] +:create+, +:update+, +:destroy+ and/or +:publish+.
+    #   +:publish+ submits after create or update while the record is published (see +published+) and
+    #   after the update that unpublishes it, so search engines also learn about removals.
+    # @param url [Symbol, #call] method name or +(record) -> String | Array<String>+ (paths are folded onto
+    #   the canonical origin)
+    # @param published [Symbol, #call] predicate for +:publish+ (default +:published?+)
+    # @param if [Symbol, #call, nil] extra condition
+    # @return [void]
+    def seo_geo_indexnow(on: %i[create update destroy], url:, published: :published?, if: nil)
+      events = Array(on).map(&:to_sym)
+      unknown = events - EVENTS
+      raise ConfigurationError, "seo_geo_indexnow on: unknown event(s) #{unknown.inspect}" unless unknown.empty?
+      raise ConfigurationError, "seo_geo_indexnow needs url: (a method name or a callable)" if url.nil?
+
+      condition = binding.local_variable_get(:if)
+      commit_on = events.flat_map { |event| event == :publish ? %i[create update] : [event] }.uniq
+
+      after_commit(on: commit_on) do
+        Model.submit_for(self, events: events, url: url, published: published, condition: condition)
+      end
+    end
+
+    class << self
+      # @api private
+      def submit_for(record, events:, url:, published:, condition:)
+        return unless call_option(record, condition, default: true)
+        return unless publish_relevant?(record, events, published)
+
+        urls = call_option(record, url, default: nil)
+        SeoGeo::IndexNow.submit(urls) if urls
+      rescue StandardError => e
+        # A failed notification must never break the transaction's callbacks chain.
+        SeoGeo::IndexNow.logger.error("[seo_geo] IndexNow submit failed for #{record.class}: #{e.class}: #{e.message}")
+        nil
+      end
+
+      private
+
+      # Explicit :create/:update/:destroy events always submit. :publish alone submits only while
+      # published, or right after the update that unpublished the record.
+      def publish_relevant?(record, events, published)
+        return true unless events.include?(:publish)
+        return true if (events & %i[create update destroy]).any? { |event| fired?(record, event) }
+        return true if call_option(record, published, default: true)
+
+        was_published?(record, published)
+      end
+
+      def fired?(record, event)
+        case event
+        when :create then record.respond_to?(:previously_new_record?) && record.previously_new_record?
+        when :destroy then record.respond_to?(:destroyed?) && record.destroyed?
+        when :update
+          !(record.respond_to?(:previously_new_record?) && record.previously_new_record?) &&
+            !(record.respond_to?(:destroyed?) && record.destroyed?)
+        end
+      end
+
+      # For +published: :published?+ backed by a +published+/+published_at+/+status+ column, the
+      # saved change tells whether the record was published before this commit.
+      def was_published?(record, published)
+        return false unless published.is_a?(Symbol) && record.respond_to?(:saved_changes)
+
+        column = published.to_s.delete_suffix("?")
+        change = record.saved_changes[column] || record.saved_changes["#{column}_at"]
+        return false unless change
+
+        before = change.first
+        before.respond_to?(:empty?) ? !before.empty? : !!before
+      end
+
+      def call_option(record, option, default:)
+        case option
+        when nil then default
+        when Symbol, String then record.respond_to?(option) ? record.public_send(option) : default
+        else option.arity.zero? ? record.instance_exec(&option) : option.call(record)
+        end
+      end
+    end
+  end
+end