analytics_ops 0.2.0 → 0.3.0

data/lib/analytics_ops/reports/metadata.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module AnalyticsOps
+  module Reports
+    # One gem-owned field returned by the GA4 metadata endpoint.
+    class Field < Resources::Value
+      fields :api_name, :ui_name, :description, :category, :kind,
+             :custom_definition, :deprecated_api_names, :data_type,
+             :expression, :blocked_reasons
+    end
+
+    # Immutable property-aware catalog of report dimensions and metrics.
+    class Metadata
+      attr_reader :property_id, :dimensions, :metrics
+
+      def initialize(property_id:, dimensions:, metrics:)
+        unless property_id.is_a?(String) && property_id.match?(/\A\d{1,50}\z/)
+          raise RemoteError, "Report metadata property ID is invalid"
+        end
+        unless dimensions.is_a?(Array) && dimensions.all?(Field) &&
+               metrics.is_a?(Array) && metrics.all?(Field)
+          raise RemoteError, "Report metadata fields are invalid"
+        end
+
+        @property_id = property_id.dup.freeze
+        @dimensions = dimensions.dup.freeze
+        @metrics = metrics.dup.freeze
+        freeze
+      end
+
+      def search(query = nil, kind: nil)
+        values = fields_for(kind)
+        return values.freeze if query.nil?
+
+        validate_query!(query)
+        return values.freeze if query.empty?
+
+        needle = query.downcase
+        matches = values.select do |field|
+          [field.api_name, field.ui_name, field.description, field.category].compact.any? do |value|
+            value.downcase.include?(needle)
+          end
+        end
+        matches.freeze
+      end
+
+      def to_h
+        {
+          "property_id" => property_id,
+          "dimensions" => dimensions.map(&:to_h),
+          "metrics" => metrics.map(&:to_h)
+        }
+      end
+
+      private
+
+      def fields_for(kind)
+        case kind&.to_s
+        when nil then dimensions + metrics
+        when "dimension" then dimensions
+        when "metric" then metrics
+        else raise InvalidRequestError, "Field kind must be dimension or metric"
+        end
+      end
+
+      def validate_query!(value)
+        return if value.is_a?(String) && value.length <= 128 && !value.match?(/[\u0000-\u001f\u007f]/)
+
+        raise InvalidRequestError, "Field search must be a printable string of at most 128 characters"
+      end
+    end
+
+    # Immutable search result with enough context for human and JSON output.
+    class FieldList
+      attr_reader :property_id, :query, :kind, :fields
+
+      def initialize(property_id:, query:, kind:, fields:)
+        @property_id = property_id.dup.freeze
+        @query = query&.dup&.freeze
+        @kind = kind&.dup&.freeze
+        @fields = fields.dup.freeze
+        freeze
+      end
+
+      def to_h
+        {
+          "property_id" => property_id,
+          "query" => query,
+          "kind" => kind,
+          "fields" => fields.map(&:to_h)
+        }
+      end
+    end
+
+    # One discoverable built-in or configured report recipe.
+    class Recipe < Resources::Value
+      fields :name, :kind, :source, :dimensions, :metrics
+    end
+
+    # Immutable list of discoverable report recipes.
+    class RecipeList
+      attr_reader :recipes
+
+      def initialize(recipes:)
+        raise ArgumentError, "recipes must contain report recipes" unless recipes.is_a?(Array) && recipes.all?(Recipe)
+
+        @recipes = recipes.dup.freeze
+        freeze
+      end
+
+      def to_h
+        { "recipes" => recipes.map(&:to_h) }
+      end
+    end
+
+    # Property-aware compatibility result for one immutable report definition.
+    class Compatibility
+      attr_reader :report_name, :compatible, :dimensions, :metrics
+
+      def initialize(report_name:, dimensions:, metrics:)
+        @report_name = validate_name(report_name)
+        @dimensions = normalize_entries(dimensions, "dimensions")
+        @metrics = normalize_entries(metrics, "metrics")
+        @compatible = (@dimensions + @metrics).all? { |entry| entry.fetch("compatibility") == "compatible" }
+        freeze
+      end
+
+      def to_h
+        {
+          "report_name" => report_name,
+          "compatible" => compatible,
+          "dimensions" => dimensions,
+          "metrics" => metrics
+        }
+      end
+
+      private
+
+      def validate_name(value)
+        return value.dup.freeze if value.is_a?(String) && Definition::REPORT_NAME.match?(value)
+
+        raise RemoteError, "Compatibility report name is invalid"
+      end
+
+      def normalize_entries(values, label)
+        valid = values.is_a?(Array) && values.all? do |entry|
+          entry.is_a?(Hash) &&
+            entry.keys.sort == %w[api_name compatibility] &&
+            entry["api_name"].is_a?(String) &&
+            entry["compatibility"].is_a?(String)
+        end
+        raise RemoteError, "Compatibility #{label} are invalid" unless valid
+
+        Canonical.immutable(values)
+      end
+    end
+  end
+end

data/lib/analytics_ops/reports/period.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "date"
+
+module AnalyticsOps
+  module Reports
+    # Builds bounded GA4 date ranges for simple CLI and AI report requests.
+    module Period
+      DEFAULT_DAYS = 28
+      MAX_DAYS = 1_825
+      ISO_DATE = /\A\d{4}-\d{2}-\d{2}\z/
+
+      module_function
+
+      def resolve(last_days: nil, start_date: nil, end_date: nil, compare: false)
+        validate_compare!(compare)
+        validate_combination!(last_days:, start_date:, end_date:)
+        return nil if last_days.nil? && start_date.nil? && !compare
+
+        if start_date
+          absolute_ranges(start_date:, end_date:, compare:)
+        else
+          relative_ranges(last_days || DEFAULT_DAYS, compare)
+        end
+      end
+
+      def relative_ranges(days, compare)
+        validate_days!(days)
+        current = {
+          "start_date" => "#{days}daysAgo",
+          "end_date" => "yesterday"
+        }
+        return Canonical.immutable([current]) unless compare
+
+        current["name"] = "current"
+        previous = {
+          "start_date" => "#{days * 2}daysAgo",
+          "end_date" => "#{days + 1}daysAgo",
+          "name" => "previous"
+        }
+        Canonical.immutable([current, previous])
+      end
+      private_class_method :relative_ranges
+
+      def absolute_ranges(start_date:, end_date:, compare:)
+        start_value = parse_date!(start_date, "--from")
+        end_value = parse_date!(end_date, "--to")
+        raise InvalidRequestError, "--from must not be after --to" if start_value > end_value
+
+        current = {
+          "start_date" => start_value.iso8601,
+          "end_date" => end_value.iso8601
+        }
+        days = (end_value - start_value).to_i + 1
+        raise InvalidRequestError, "Date range cannot exceed #{MAX_DAYS} days" if days > MAX_DAYS
+        return Canonical.immutable([current]) unless compare
+
+        previous_end = start_value - 1
+        previous_start = previous_end - (days - 1)
+        current["name"] = "current"
+        previous = {
+          "start_date" => previous_start.iso8601,
+          "end_date" => previous_end.iso8601,
+          "name" => "previous"
+        }
+        Canonical.immutable([current, previous])
+      end
+      private_class_method :absolute_ranges
+
+      def validate_combination!(last_days:, start_date:, end_date:)
+        if last_days && (start_date || end_date)
+          raise InvalidRequestError, "Use either --last or --from with --to, not both"
+        end
+        return if start_date.nil? == end_date.nil?
+
+        raise InvalidRequestError, "--from and --to must be used together"
+      end
+      private_class_method :validate_combination!
+
+      def validate_days!(value)
+        return if value.is_a?(Integer) && value.between?(1, MAX_DAYS)
+
+        raise InvalidRequestError, "--last must be between 1 and #{MAX_DAYS} days"
+      end
+      private_class_method :validate_days!
+
+      def validate_compare!(value)
+        return if [true, false].include?(value)
+
+        raise InvalidRequestError, "--compare must be true or false"
+      end
+      private_class_method :validate_compare!
+
+      def parse_date!(value, option)
+        raise InvalidRequestError, "#{option} must use YYYY-MM-DD" unless value.is_a?(String) && ISO_DATE.match?(value)
+
+        Date.iso8601(value)
+      rescue Date::Error
+        raise InvalidRequestError, "#{option} must be a real calendar date"
+      end
+      private_class_method :parse_date!
+    end
+  end
+end

data/lib/analytics_ops/reports/result.rb

@@ -4,6 +4,9 @@ module AnalyticsOps
   module Reports
     # Immutable normalized Data API response.
     class Result
+      MAX_ROWS = Definition::MAX_STANDARD_LIMIT
+      MAX_CELL_BYTES = 1_048_576
+
       attr_reader :name, :kind, :dimension_headers, :metric_headers, :headers, :rows, :row_count, :metadata
 
       def initialize(name:, kind:, dimension_headers:, metric_headers:, rows:, row_count:, metadata:)
@@ -59,13 +62,15 @@ module AnalyticsOps
       end
 
       def normalized_rows(values)
-        raise RemoteError, "Report result rows must be an array" unless values.is_a?(Array)
+        unless values.is_a?(Array) && values.length <= MAX_ROWS
+          raise RemoteError, "Report result rows must be a bounded array"
+        end
 
         normalized = values.map do |row|
           value = hash(row, "row")
           raise RemoteError, "Report result row fields do not match headers" unless value.keys.sort == headers.sort
-          unless value.values.all? { |item| valid_utf8?(item) }
-            raise RemoteError, "Report result row values must be valid UTF-8 strings"
+          unless value.values.all? { |item| valid_utf8?(item) && item.bytesize <= MAX_CELL_BYTES }
+            raise RemoteError, "Report result row values must be bounded valid UTF-8 strings"
           end
 
           value

data/lib/analytics_ops/reports.rb

@@ -3,10 +3,13 @@
 # Reporting public namespace.
 
 require_relative "reports/definition"
+require_relative "reports/metadata"
+require_relative "reports/period"
 require_relative "reports/catalog"
 require_relative "reports/overview"
 require_relative "reports/result"
 require_relative "reports/overview_result"
+require_relative "reports/csv_export"
 
 module AnalyticsOps
   # Immutable Data API definitions, recipes, and normalized results.