ahoy_analytics 0.1.0

data/app/models/ahoy/visit/filters.rb

@@ -0,0 +1,286 @@
+module Ahoy::Visit::Filters
+  extend ActiveSupport::Concern
+
+  class_methods do
+    # Build a case-insensitive SQL LIKE pattern that safely treats user input literally
+    def like_contains(value)
+      "%#{ActiveRecord::Base.sanitize_sql_like(value.to_s.downcase)}%"
+    end
+
+    def normalized_filter(filters, key)
+      return unless filters
+      value = filters[key]&.to_s
+      return unless value
+      value.strip.downcase.tr(" ", "-")
+    end
+
+    def filtered_visits(filters, advanced_filters: [])
+      scope = Ahoy::Visit.all
+
+      if filters.present?
+        if (source = filters["source"]).present?
+          s_down = source.to_s.downcase.strip
+          if %w[direct / none (none) direct none directlink].include?(s_down)
+            scope = scope.where(referring_domain: [ nil, "" ])
+          elsif (pattern = domain_pattern_for_source_label(source))
+            aliases = alias_sources_map.select { |_k, v| v.to_s.downcase == s_down }.keys
+            if aliases.any?
+              scope = scope.where(
+                "referring_domain ~* ? OR LOWER(utm_source) IN (?) OR LOWER(utm_source) LIKE ?",
+                pattern, aliases, "#{s_down}%"
+              )
+            else
+              scope = scope.where(
+                "referring_domain ~* ? OR LOWER(utm_source) = ? OR LOWER(utm_source) LIKE ?",
+                pattern, s_down, "#{s_down}%"
+              )
+            end
+          else
+            if source.include?(".")
+              scope = scope.where(referring_domain: source)
+            else
+              like = like_contains(source)
+              scope = scope.where("LOWER(referring_domain) LIKE ? OR LOWER(utm_source) LIKE ?", like, like)
+            end
+          end
+        elsif normalized_filter(filters, "source") == "direct"
+          scope = scope.where(referring_domain: [ nil, "" ])
+        end
+
+        if (channel = filters["channel"]).present?
+          val = Ahoy::Visit.connection.quote(channel)
+          cond = "(#{Ahoy::Visit::Sources::CHANNEL_CASE_SQL}) = #{val}"
+          scope = scope.where(Arel.sql(cond))
+        end
+        scope = scope.where(referrer: filters["referrer"]) if filters["referrer"].present?
+        scope = scope.where(country: filters["country"]) if filters["country"].present?
+        scope = scope.where(region:  filters["region"])  if filters["region"].present?
+        scope = scope.where(city:    filters["city"])    if filters["city"].present?
+        scope = scope.where(utm_source: filters["utm_source"]) if filters["utm_source"].present?
+        scope = scope.where(utm_medium: filters["utm_medium"]) if filters["utm_medium"].present?
+        scope = scope.where(utm_campaign: filters["utm_campaign"]) if filters["utm_campaign"].present?
+        scope = scope.where(browser: filters["browser"]) if filters["browser"].present?
+        scope = scope.where(os: filters["os"]) if filters["os"].present?
+      end
+
+      Array(advanced_filters).each do |op, dim, value|
+        if dim == "channel"
+          case op
+          when "is_not"
+            val = Ahoy::Visit.connection.quote(value)
+            cond = "(#{Ahoy::Visit::Sources::CHANNEL_CASE_SQL}) <> #{val}"
+            scope = scope.where(Arel.sql(cond))
+          when "contains"
+            pat = Ahoy::Visit.connection.quote(like_contains(value))
+            cond = "LOWER((#{Ahoy::Visit::Sources::CHANNEL_CASE_SQL})) LIKE #{pat}"
+            scope = scope.where(Arel.sql(cond))
+          end
+          next
+        end
+        if dim == "source"
+          like = like_contains(value)
+          case op
+          when "contains"
+            scope = scope.where("LOWER(referring_domain) LIKE ? OR LOWER(utm_source) LIKE ?", like, like)
+          when "is_not"
+            scope = scope.where("NOT (LOWER(referring_domain) LIKE ? OR LOWER(utm_source) LIKE ?)", like, like)
+          end
+          next
+        end
+
+        column = case dim
+        when "referrer" then "referrer"
+        when "utm_source", "utm_medium", "utm_campaign", "utm_content", "utm_term", "country", "region", "city", "browser", "os"
+          dim
+        else
+          nil
+        end
+        next unless column
+
+        if op == "is_not"
+          scope = scope.where.not(Arel.sql(column) => value)
+        elsif op == "contains"
+          scope = scope.where("LOWER(#{column}) LIKE ?", like_contains(value))
+        end
+      end
+
+      scope
+    end
+
+    def scoped_visits(range, filters, advanced_filters: [])
+      basic_filters = filters.to_h.dup
+      exit_page = basic_filters&.delete("exit_page")
+      page_eq   = basic_filters&.delete("page")
+      size_eq   = basic_filters&.delete("size")
+
+      visits = filtered_visits(basic_filters, advanced_filters: advanced_filters).where(started_at: range)
+
+      if (entry = filters["entry_page"]).present?
+        decoded = begin
+          CGI.unescape(entry.to_s)
+        rescue StandardError
+          entry.to_s
+        end
+        raw = normalized_path_and_query(decoded) || decoded
+        label = raw.to_s.split("?").first.presence || "/"
+
+        expr = "COALESCE(CASE WHEN strpos(regexp_replace(landing_page, '^(https://|http://)[^/]+', ''), chr(63)) > 0 THEN left(regexp_replace(landing_page, '^(https://|http://)[^/]+', ''), strpos(regexp_replace(landing_page, '^(https://|http://)[^/]+', ''), chr(63)) - 1) ELSE NULLIF(regexp_replace(landing_page, '^(https://|http://)[^/]+', ''), '') END, '/')"
+        by_landing = visits.where(Arel.sql("#{expr} = ?"), label)
+
+        candidate_ids = visits
+          .where("landing_page IS NULL OR landing_page = '' OR regexp_replace(landing_page, '^(https://|http://)[^/]+', '') SIMILAR TO ?", "(/ahoy%|/cable%|/rails/%|/assets/%|/up%|/jobs%|/webhooks%)")
+          .pluck(:id)
+
+        derived_ids = []
+        if candidate_ids.any?
+          ev_rows = Ahoy::Event
+            .where(name: "pageview", time: range, visit_id: candidate_ids)
+            .pluck(Arel.sql("visit_id, time, COALESCE(ahoy_events.properties->>'page', '')"))
+          first_page_by_visit = {}
+          ev_rows.each do |vid, t, pg|
+            prev = first_page_by_visit[vid]
+            t_val = t.respond_to?(:to_time) ? t.to_time : t
+            if prev.nil? || t_val < prev[0]
+              first_page_by_visit[vid] = [ t_val, pg.to_s ]
+            end
+          end
+          first_page_by_visit.each do |vid, (_t, pg)|
+            next if pg.to_s.strip.empty?
+            lp = normalized_path_only(pg)
+            derived_ids << vid if lp.to_s == label
+          end
+        end
+
+        visits = by_landing.or(visits.where(id: derived_ids.presence || [ 0 ]))
+      end
+
+      if exit_page.present?
+        ids = visit_ids_with_exit_page(range, visits, exit_page)
+        visits = visits.where(id: ids.presence || [ 0 ])
+      end
+
+      if page_eq.present?
+        sub = Ahoy::Event
+          .where(name: "pageview")
+          .where(visit_id: visits.select(:id))
+          .where(Arel.sql("ahoy_events.properties->>'page' = ?"), page_eq)
+          .select(:visit_id)
+          .distinct
+        visits = visits.where(id: sub)
+      end
+
+      if size_eq.present?
+        ids = visit_ids_for_screen_size_categories(visits, [ size_eq ])
+        visits = visits.where(id: ids.presence || [ 0 ])
+      end
+
+      Array(advanced_filters).each do |op, dim, value|
+        next unless dim == "page"
+        next if value.to_s.strip.empty?
+        case op
+        when "contains"
+          sub = Ahoy::Event
+            .where(name: "pageview")
+            .where(visit_id: visits.select(:id))
+            .where("LOWER(ahoy_events.properties->>'page') LIKE ?", like_contains(value))
+            .select(:visit_id).distinct
+          visits = visits.where(id: sub)
+        when "is_not"
+          sub = Ahoy::Event
+            .where(name: "pageview")
+            .where(visit_id: visits.select(:id))
+            .where(Arel.sql("ahoy_events.properties->>'page' = ?"), value)
+            .select(:visit_id).distinct
+          visits = visits.where.not(id: sub)
+        end
+      end
+
+      Array(advanced_filters).each do |op, dim, value|
+        next unless dim == "size"
+        needle = value.to_s.strip.downcase
+        next if needle.empty?
+
+        case op
+        when "contains"
+          categories = %w[Mobile Tablet Laptop Desktop (not\ set)].select { |c| c.downcase.include?(needle) }
+          ids = visit_ids_for_screen_size_categories(visits, categories)
+          visits = visits.where(id: ids.presence || [ 0 ])
+        when "is_not"
+          ids = visit_ids_for_screen_size_categories(visits, [ value.to_s ])
+          visits = visits.where.not(id: ids.presence || [ 0 ])
+        end
+      end
+
+      visits
+    end
+
+    def scoped_events(range, filters, advanced_filters: [])
+      basic_filters = filters.to_h.dup
+      exit_page = basic_filters&.delete("exit_page")
+
+      scope = Ahoy::Event
+        .where(name: "pageview", time: range)
+        .joins(:visit)
+        .merge(filtered_visits(basic_filters, advanced_filters: advanced_filters))
+
+      if exit_page.present?
+        visit_scope = Ahoy::Visit.where(id: scope.select(:visit_id).distinct)
+        ids = visit_ids_with_exit_page(range, visit_scope, exit_page)
+        scope = scope.where(visit_id: ids.presence || [ 0 ])
+      end
+
+      if filters["page"].present?
+        scope = scope.where(Arel.sql("ahoy_events.properties->>'page' = ?"), filters["page"])
+      end
+
+      Array(advanced_filters).each do |op, dim, value|
+        next unless dim == "page"
+        if op == "is_not"
+          scope = scope.where.not(Arel.sql("ahoy_events.properties->>'page' = ?"), value)
+        elsif op == "contains"
+          scope = scope.where("LOWER(ahoy_events.properties->>'page') LIKE ?", like_contains(value))
+        end
+      end
+
+      scope
+    end
+
+    def visit_ids_with_exit_page(range, visits_scope, exit_page)
+      return [] if visits_scope.none?
+
+      expr = "COALESCE(NULLIF(split_part(ahoy_events.properties->>'page', '?', 1), ''), '')"
+      rows = Ahoy::Event
+        .where(name: "pageview", time: range)
+        .where(visit_id: visits_scope.select(:id))
+        .pluck(Arel.sql("visit_id, time, #{expr}"))
+
+      last_page_by_visit = {}
+      rows.each do |vid, t, page_name|
+        prev = last_page_by_visit[vid]
+        t_val = t.respond_to?(:to_time) ? t.to_time : t
+        prev_time = prev ? (prev.is_a?(Array) ? prev[0] : prev.first) : nil
+        if prev.nil? || t_val > prev_time
+          last_page_by_visit[vid] = [ t_val, page_name.to_s ]
+        end
+      end
+
+      needle = exit_page.to_s.split("?").first
+      last_page_by_visit.filter_map { |vid, (_t, page)| vid if page == needle }
+    end
+
+    def visit_ids_for_screen_size_categories(visits_scope, categories)
+      return [] if visits_scope.none?
+
+      raw = visits_scope.group(:screen_size).pluck(:screen_size, Arel.sql("ARRAY_AGG(id)"))
+      categories_down = categories.map(&:to_s)
+      selected = []
+      raw.each do |screen_size, visit_ids|
+        cat = categorize_screen_size(screen_size)
+        if categories_down.any? { |c| c.to_s == cat.to_s }
+          selected.concat(Array(visit_ids))
+        end
+      end
+      selected
+    end
+  end
+end

data/app/models/ahoy/visit/imports.rb

@@ -0,0 +1,36 @@
+module Ahoy::Visit::Imports
+  extend ActiveSupport::Concern
+
+  class_methods do
+    def imported_pages_aggregates(range)
+      rows = AhoyAnalytics::ImportedPage.where(date: range).group(:page)
+        .pluck(:page, Arel.sql("SUM(visitors), SUM(pageviews)"))
+      rows.each_with_object({}) do |(page, visitors, pageviews), h|
+        name = page.to_s.presence || "(unknown)"
+        h[name] = { visitors: visitors.to_i, pageviews: pageviews.to_i }
+      end
+    end
+
+    def imported_entry_aggregates(range)
+      rows = AhoyAnalytics::ImportedEntryPage.where(date: range).group(:entry_page)
+        .pluck(:entry_page, Arel.sql("SUM(visitors), SUM(entrances)"))
+      rows.each_with_object({}) do |(page, visitors, entrances), h|
+        name = page.to_s.presence || "(unknown)"
+        h[name] = { visitors: visitors.to_i, entrances: entrances.to_i }
+      end
+    end
+
+    def imported_exit_aggregates(range)
+      rows = AhoyAnalytics::ImportedExitPage.where(date: range).group(:exit_page)
+        .pluck(:exit_page, Arel.sql("SUM(visitors), SUM(exits), SUM(pageviews)"))
+      rows.each_with_object({}) do |(page, visitors, exits, pageviews), h|
+        name = page.to_s.presence || "(unknown)"
+        h[name] = { visitors: visitors.to_i, exits: exits.to_i, pageviews: pageviews.to_i }
+      end
+    end
+
+    def skip_imported_reason(query)
+      query[:with_imported] ? "not_supported" : nil
+    end
+  end
+end

data/app/models/ahoy/visit/locations.rb

@@ -0,0 +1,276 @@
+module Ahoy::Visit::Locations
+  extend ActiveSupport::Concern
+
+  class_methods do
+    def locations_payload(query, limit: nil, page: nil, search: nil, order_by: nil)
+      mode = query[:mode] || "map"
+      filters = query[:filters] || {}
+      range, = Ahoy::Visit.range_and_interval_for(query[:period], nil, query)
+      visits = Ahoy::Visit.scoped_visits(range, filters)
+      goal = filters["goal"].presence
+
+      case mode
+      when "map"
+        counts = visits.group(:country).count("DISTINCT visitor_token")
+        map_from_counts(counts)
+      when "countries"
+        if limit && page
+          expr = "COALESCE(country, '(unknown)')"
+          pattern = search.present? ? Ahoy::Visit.like_contains(search) : nil
+          rel = visits
+          rel = rel.where("LOWER(COALESCE(country, '(unknown)')) LIKE ?", pattern) if pattern.present?
+          grouped_visit_ids = rel.group(Arel.sql(expr)).pluck(Arel.sql("#{expr}, ARRAY_AGG(ahoy_visits.id)")).to_h
+          counts = Ahoy::Visit.unique_counts_from_grouped_visit_ids(grouped_visit_ids, visits)
+          total = counts.values.sum.nonzero? || 1
+
+          if goal.present?
+            conversions, cr = Ahoy::Visit.conversions_and_rates(grouped_visit_ids, visits, range, filters, goal)
+            sorted_names = Ahoy::Visit.order_names_with_conversions(conversions: conversions, cr: cr, order_by: order_by)
+
+            paged_names, has_more = Ahoy::Visit.paginate_names(sorted_names, limit: limit, page: page)
+
+            items = paged_names.map do |code|
+              code_str = code.to_s
+              name = if code_str.present? && code_str != "(unknown)"
+                c = ISO3166::Country.new(code_str.upcase)
+                c ? short_country_name(c) : code_str
+              else
+                "(unknown)"
+              end
+              { name: name, code: code_str != "(unknown)" ? code_str : nil, visitors: conversions[code] || 0, conversion_rate: cr[code] }.compact
+            end
+            { results: items, metrics: %i[visitors conversion_rate], meta: { has_more: has_more, skip_imported_reason: Ahoy::Visit.skip_imported_reason(query), metric_labels: { visitors: "Conversions", conversionRate: "Conversion Rate" } } }
+          else
+            sorted_names = begin
+              if order_by && order_by[0] == "percentage"
+                perc = counts.keys.index_with { |k| { percentage: (counts[k].to_f / total) } }
+                Ahoy::Visit.order_names(counts: counts, metrics_map: perc, order_by: order_by)
+              else
+                Ahoy::Visit.order_names(counts: counts, metrics_map: {}, order_by: order_by)
+              end
+            end
+
+            paged_names, has_more = Ahoy::Visit.paginate_names(sorted_names, limit: limit, page: page)
+
+            items = paged_names.map do |code|
+              v = counts[code]
+              code_str = code.to_s
+              name = if code_str.present? && code_str != "(unknown)"
+                c = ISO3166::Country.new(code_str.upcase)
+                c ? short_country_name(c) : code_str
+              else
+                "(unknown)"
+              end
+              { name: name, code: code_str != "(unknown)" ? code_str : nil, visitors: v, percentage: (v.to_f / total).round(3) }.compact
+            end
+            { results: items, metrics: %i[visitors percentage], meta: { has_more: has_more, skip_imported_reason: Ahoy::Visit.skip_imported_reason(query), metric_labels: { percentage: "Percentage" } } }
+          end
+        else
+          counts = visits.group(:country).count("DISTINCT visitor_token")
+          items = counts.map do |code, v|
+            code_str = code.to_s
+            if code_str.present?
+              c = ISO3166::Country.new(code_str.upcase)
+              if c
+                { name: short_country_name(c), code: c.alpha2, visitors: v }
+              else
+                { name: code_str, visitors: v }
+              end
+            else
+              { name: "(unknown)", visitors: v }
+            end
+          end
+          items = items.sort_by { |it| [ -it[:visitors].to_i, it[:name].to_s ] }
+          { results: items, metrics: %i[visitors], meta: { has_more: false, skip_imported_reason: Ahoy::Visit.skip_imported_reason(query) } }
+        end
+      when "regions"
+        if limit && page
+          expr = "COALESCE(region, '(unknown)')"
+          pattern = search.present? ? Ahoy::Visit.like_contains(search) : nil
+          rel = visits
+          rel = rel.where("LOWER(COALESCE(region, '(unknown)')) LIKE ?", pattern) if pattern.present?
+          grouped_visit_ids = rel.group(Arel.sql(expr)).pluck(Arel.sql("#{expr}, ARRAY_AGG(ahoy_visits.id)")).to_h
+          counts = Ahoy::Visit.unique_counts_from_grouped_visit_ids(grouped_visit_ids, visits)
+
+          if goal.present?
+            conversions, cr = Ahoy::Visit.conversions_and_rates(grouped_visit_ids, visits, range, filters, goal)
+            sorted_names = Ahoy::Visit.order_names_with_conversions(conversions: conversions, cr: cr, order_by: order_by)
+
+            paged_names, has_more = Ahoy::Visit.paginate_names(sorted_names, limit: limit, page: page)
+            flags_by_region = country_flags_for_grouped(grouped_visit_ids.slice(*paged_names), visits, :region, filters)
+            results = paged_names.map do |name|
+              { name: name.to_s.presence || "(none)", visitors: conversions[name] || 0, conversion_rate: cr[name], country_flag: flags_by_region[name] }.compact
+            end
+            { results: results, metrics: %i[visitors conversion_rate], meta: { has_more: has_more, skip_imported_reason: Ahoy::Visit.skip_imported_reason(query), metric_labels: { visitors: "Conversions", conversionRate: "Conversion Rate" } } }
+          else
+            sorted_names = Ahoy::Visit.order_names(counts: counts, metrics_map: {}, order_by: order_by)
+
+            paged_names, has_more = Ahoy::Visit.paginate_names(sorted_names, limit: limit, page: page)
+            flags_by_region = country_flags_for_grouped(grouped_visit_ids.slice(*paged_names), visits, :region, filters)
+            results = paged_names.map do |name|
+              v = counts[name]
+              { name: name.to_s.presence || "(none)", visitors: v, country_flag: flags_by_region[name] }.compact
+            end
+            { results: results, metrics: %i[visitors], meta: { has_more: has_more, skip_imported_reason: Ahoy::Visit.skip_imported_reason(query) } }
+          end
+        else
+          counts = visits.group(:region).count("DISTINCT visitor_token")
+          flags_by_region = if filters[:country].present?
+            code = filters[:country].to_s.upcase
+            flag = emoji_flag_for(code)
+            counts.keys.each_with_object({}) { |r, h| h[r] = flag }
+          else
+            pairs = visits.group(:region, :country).count("DISTINCT visitor_token")
+            dominant = Hash.new { |h, k| h[k] = { country: nil, count: -1 } }
+            pairs.each do |(region, country), c|
+              next if region.blank?
+              cur = dominant[region]
+              if c.to_i > cur[:count].to_i
+                dominant[region] = { country: country, count: c.to_i }
+              end
+            end
+            dominant.transform_values { |v| emoji_flag_for(v[:country].to_s.upcase) }
+          end
+
+          rows = counts.sort_by { |_, v| -v.to_i }.map do |(name, v)|
+            label = name.to_s.presence || "(unknown)"
+            h = { name: label, visitors: v }
+            flag = flags_by_region[name]
+            flag.present? ? h.merge(country_flag: flag) : h
+          end
+          { results: rows, metrics: %i[visitors], meta: { has_more: false, skip_imported_reason: Ahoy::Visit.skip_imported_reason(query) } }
+        end
+      when "cities"
+        if limit && page
+          expr = "COALESCE(city, '(unknown)')"
+          pattern = search.present? ? Ahoy::Visit.like_contains(search) : nil
+          rel = visits
+          rel = rel.where("LOWER(COALESCE(city, '(unknown)')) LIKE ?", pattern) if pattern.present?
+          grouped_visit_ids = rel.group(Arel.sql(expr)).pluck(Arel.sql("#{expr}, ARRAY_AGG(ahoy_visits.id)")).to_h
+          counts = Ahoy::Visit.unique_counts_from_grouped_visit_ids(grouped_visit_ids, visits)
+
+          if goal.present?
+            conversions, cr = Ahoy::Visit.conversions_and_rates(grouped_visit_ids, visits, range, filters, goal)
+            sorted_names = Ahoy::Visit.order_names_with_conversions(conversions: conversions, cr: cr, order_by: order_by)
+
+            paged_names, has_more = Ahoy::Visit.paginate_names(sorted_names, limit: limit, page: page)
+            flags_by_city = country_flags_for_grouped(grouped_visit_ids.slice(*paged_names), visits, :city, filters)
+            results = paged_names.map do |name|
+              { name: name.to_s.presence || "(none)", visitors: conversions[name] || 0, conversion_rate: cr[name], country_flag: flags_by_city[name] }.compact
+            end
+            { results: results, metrics: %i[visitors conversion_rate], meta: { has_more: has_more, skip_imported_reason: Ahoy::Visit.skip_imported_reason(query), metric_labels: { visitors: "Conversions", conversionRate: "Conversion Rate" } } }
+          else
+            sorted_names = Ahoy::Visit.order_names(counts: counts, metrics_map: {}, order_by: order_by)
+
+            paged_names, has_more = Ahoy::Visit.paginate_names(sorted_names, limit: limit, page: page)
+            flags_by_city = country_flags_for_grouped(grouped_visit_ids.slice(*paged_names), visits, :city, filters)
+            results = paged_names.map do |name|
+              v = counts[name]
+              { name: name.to_s.presence || "(none)", visitors: v, country_flag: flags_by_city[name] }.compact
+            end
+            { results: results, metrics: %i[visitors], meta: { has_more: has_more, skip_imported_reason: Ahoy::Visit.skip_imported_reason(query) } }
+          end
+        else
+          counts = visits.group(:city).count("DISTINCT visitor_token")
+          flags_by_city = if filters[:country].present?
+            code = filters[:country].to_s.upcase
+            flag = emoji_flag_for(code)
+            counts.keys.each_with_object({}) { |c, h| h[c] = flag }
+          else
+            pairs = visits.group(:city, :country).count("DISTINCT visitor_token")
+            dominant = Hash.new { |h, k| h[k] = { country: nil, count: -1 } }
+            pairs.each do |(city, country), c|
+              next if city.blank?
+              cur = dominant[city]
+              if c.to_i > cur[:count].to_i
+                dominant[city] = { country: country, count: c.to_i }
+              end
+            end
+            dominant.transform_values { |v| emoji_flag_for(v[:country].to_s.upcase) }
+          end
+
+          rows = counts.sort_by { |_, v| -v.to_i }.map do |(name, v)|
+            label = name.to_s.presence || "(unknown)"
+            h = { name: label, visitors: v }
+            flag = flags_by_city[name]
+            flag.present? ? h.merge(country_flag: flag) : h
+          end
+          { results: rows, metrics: %i[visitors], meta: { has_more: false, skip_imported_reason: Ahoy::Visit.skip_imported_reason(query) } }
+        end
+      else
+        counts = visits.group(:country).count
+        rows = counts.sort_by { |_, v| -v }.map { |(name, v)| { name: name.to_s.presence || "(none)", visitors: v } }
+        { results: rows, metrics: %i[visitors], meta: { has_more: false, skip_imported_reason: Ahoy::Visit.skip_imported_reason(query) } }
+      end
+    end
+
+    def map_from_counts(counts)
+      total = counts.values.sum
+      results = counts
+        .sort_by { |_, v| -v }
+        .filter_map do |(code, visitors)|
+          next if code.blank?
+          normalized = code.to_s.upcase
+          country = ISO3166::Country.new(normalized)
+          next unless country
+          { alpha3: country.alpha3, alpha2: country.alpha2, numeric: country.number, code: normalized, name: short_country_name(country), visitors: visitors }
+        end
+      { map: { results: results, meta: { total: total } } }
+    end
+
+    def emoji_flag_for(code)
+      return nil if code.blank?
+      iso2 = code.to_s.upcase
+      return nil unless iso2.match?(/\A[A-Z]{2}\z/)
+      base = 0x1F1E6
+      iso2.each_char.map { |ch| (base + (ch.ord - "A".ord)).chr(Encoding::UTF_8) }.join
+    rescue
+      nil
+    end
+
+    def country_flags_for_grouped(grouped_visit_ids, visits_relation, dimension, filters)
+      return {} if grouped_visit_ids.blank?
+      if filters[:country].present?
+        flag = emoji_flag_for(filters[:country].to_s.upcase)
+        return grouped_visit_ids.keys.each_with_object({}) { |name, h| h[name] = flag }
+      end
+      all_ids = grouped_visit_ids.values.flatten.uniq
+      return {} if all_ids.empty?
+      pairs = visits_relation.where(id: all_ids).group(dimension, :country).count
+      best = {}
+      pairs.each do |(name, country), c|
+        next if name.blank?
+        prev = best[name]
+        if prev.nil? || c.to_i > prev[:count].to_i
+          best[name] = { country: country, count: c.to_i }
+        end
+      end
+      best.transform_values { |v| emoji_flag_for(v[:country].to_s.upcase) }
+    rescue
+      {}
+    end
+
+    def alpha3_for(code)
+      country = ISO3166::Country.new(code)
+      country&.alpha3 || code
+    end
+
+    def country_name_for(code)
+      country = ISO3166::Country.new(code)
+      country ? short_country_name(country) : code
+    end
+
+    def short_country_name(country)
+      return "" unless country
+      name = country.respond_to?(:common_name) && country.common_name.present? ? country.common_name : country.iso_short_name.to_s
+      name = name.to_s.gsub(/\s*\(the\)\s*\z/i, "").gsub(/\s{2,}/, " ").strip
+      case name
+      when "Viet Nam" then "Vietnam"
+      when "Korea (Republic of)" then "South Korea"
+      when "Korea (Democratic People's Republic of)" then "North Korea"
+      else
+        name
+      end
+    end
+  end
+end