analytics_ops 0.2.0 → 0.3.0

data/lib/analytics_ops/configuration/schema.rb

@@ -47,7 +47,13 @@ module AnalyticsOps
             "manual_requirements" => {
               "type" => "array", "uniqueItems" => true,
               "items" => { "type" => "string", "pattern" => "^[A-Za-z][A-Za-z0-9_]{0,63}$" }
-            }
+            },
+            "labels" => { "$ref" => "#/$defs/labels" },
+            "reports" => { "$ref" => "#/$defs/reports" },
+            "health" => { "$ref" => "#/$defs/health" },
+            "governance" => { "$ref" => "#/$defs/governance" },
+            "bigquery" => { "$ref" => "#/$defs/bigquery" },
+            "funnels" => { "$ref" => "#/$defs/funnels" }
           }
         },
         "stream" => {
@@ -143,6 +149,174 @@ module AnalyticsOps
               "else" => { "properties" => { "restricted_metric_types" => { "maxItems" => 0 } } }
             }
           ]
+        },
+        "labels" => {
+          "type" => "object",
+          "maxProperties" => 16,
+          "propertyNames" => { "pattern" => "^[A-Za-z][A-Za-z0-9_]{0,63}$" },
+          "additionalProperties" => {
+            "type" => "string", "minLength" => 1, "maxLength" => 64,
+            "pattern" => "^[^\\u0000-\\u001F\\u007F]+$"
+          }
+        },
+        "apiName" => {
+          "type" => "string",
+          "pattern" => "^[a-z][a-zA-Z0-9_]*(?::[a-zA-Z][a-zA-Z0-9_]*)?$"
+        },
+        "dateRange" => {
+          "type" => "object",
+          "additionalProperties" => false,
+          "required" => %w[start_date end_date],
+          "properties" => {
+            "start_date" => { "type" => "string" },
+            "end_date" => { "type" => "string" },
+            "name" => { "type" => "string", "pattern" => "^[a-z][a-z0-9_]{0,39}$" }
+          }
+        },
+        "filterExpression" => {
+          "oneOf" => [
+            {
+              "type" => "object", "additionalProperties" => false, "required" => ["and"],
+              "properties" => {
+                "and" => {
+                  "type" => "array", "minItems" => 2, "maxItems" => 20,
+                  "items" => { "$ref" => "#/$defs/filterExpression" }
+                }
+              }
+            },
+            {
+              "type" => "object", "additionalProperties" => false, "required" => ["or"],
+              "properties" => {
+                "or" => {
+                  "type" => "array", "minItems" => 2, "maxItems" => 20,
+                  "items" => { "$ref" => "#/$defs/filterExpression" }
+                }
+              }
+            },
+            {
+              "type" => "object", "additionalProperties" => false, "required" => ["not"],
+              "properties" => { "not" => { "$ref" => "#/$defs/filterExpression" } }
+            },
+            {
+              "type" => "object",
+              "required" => ["field"],
+              "properties" => {
+                "field" => { "$ref" => "#/$defs/apiName" },
+                "match_type" => {
+                  "enum" => Reports::Definition::MATCH_TYPES
+                },
+                "value" => { "type" => %w[string number] },
+                "case_sensitive" => { "type" => "boolean" },
+                "in_list" => {
+                  "type" => "array", "minItems" => 1, "maxItems" => 100,
+                  "uniqueItems" => true, "items" => { "type" => "string" }
+                },
+                "operation" => { "enum" => Reports::Definition::NUMERIC_OPERATIONS },
+                "between" => {
+                  "type" => "array", "minItems" => 2, "maxItems" => 2,
+                  "items" => { "type" => "number" }
+                },
+                "null" => { "const" => true }
+              },
+              "additionalProperties" => false
+            }
+          ]
+        },
+        "report" => {
+          "type" => "object",
+          "additionalProperties" => false,
+          "required" => ["metrics"],
+          "properties" => {
+            "kind" => { "enum" => Reports::Definition::KINDS },
+            "dimensions" => {
+              "type" => "array", "maxItems" => 9, "uniqueItems" => true,
+              "items" => { "$ref" => "#/$defs/apiName" }
+            },
+            "metrics" => {
+              "type" => "array", "minItems" => 1, "maxItems" => 10, "uniqueItems" => true,
+              "items" => { "$ref" => "#/$defs/apiName" }
+            },
+            "date_ranges" => {
+              "type" => "array", "maxItems" => 4, "items" => { "$ref" => "#/$defs/dateRange" }
+            },
+            "dimension_filter" => { "$ref" => "#/$defs/filterExpression" },
+            "metric_filter" => { "$ref" => "#/$defs/filterExpression" },
+            "order_bys" => { "type" => "array", "maxItems" => 10, "items" => { "type" => "object" } },
+            "limit" => { "type" => "integer", "minimum" => 1, "maximum" => 250_000 }
+          }
+        },
+        "reports" => {
+          "type" => "object", "maxProperties" => 50,
+          "propertyNames" => { "pattern" => "^[A-Za-z][A-Za-z0-9_]{0,63}$" },
+          "additionalProperties" => { "$ref" => "#/$defs/report" }
+        },
+        "health" => {
+          "type" => "object", "additionalProperties" => false,
+          "properties" => {
+            "expected_events" => {
+              "type" => "array", "uniqueItems" => true,
+              "items" => { "type" => "string", "pattern" => "^[A-Za-z][A-Za-z0-9_]{0,39}$" }
+            },
+            "minimum_sessions" => { "type" => "integer", "minimum" => 0, "maximum" => 1_000_000_000 },
+            "traffic_drop_percent" => { "type" => "number", "minimum" => 0, "maximum" => 100 },
+            "key_event_drop_percent" => { "type" => "number", "minimum" => 0, "maximum" => 100 },
+            "unassigned_percent" => { "type" => "number", "minimum" => 0, "maximum" => 100 },
+            "not_set_percent" => { "type" => "number", "minimum" => 0, "maximum" => 100 }
+          }
+        },
+        "governance" => {
+          "type" => "object", "additionalProperties" => false, "required" => ["experimental"],
+          "properties" => {
+            "experimental" => { "const" => true },
+            "enhanced_measurement_required" => { "type" => "boolean" },
+            "email_redaction_required" => { "type" => "boolean" },
+            "query_parameter_redaction_required" => { "type" => "boolean" },
+            "reporting_identity" => { "enum" => %w[blended observed device_based] },
+            "bigquery_link_required" => { "type" => "boolean" },
+            "expected_channel_groups" => { "$ref" => "#/$defs/stringList" },
+            "expected_calculated_metrics" => { "$ref" => "#/$defs/stringList" },
+            "expected_event_create_rules" => { "$ref" => "#/$defs/stringList" },
+            "expected_event_edit_rules" => { "$ref" => "#/$defs/stringList" }
+          }
+        },
+        "stringList" => {
+          "type" => "array", "uniqueItems" => true,
+          "items" => { "type" => "string", "minLength" => 1, "maxLength" => 128 }
+        },
+        "bigquery" => {
+          "type" => "object", "additionalProperties" => false,
+          "required" => %w[project_id dataset maximum_bytes_billed experimental],
+          "properties" => {
+            "project_id" => { "type" => "string", "pattern" => "^[a-z][a-z0-9-]{4,28}[a-z0-9]$" },
+            "dataset" => { "type" => "string", "pattern" => "^[A-Za-z_][A-Za-z0-9_]{0,1023}$" },
+            "location" => { "type" => "string", "pattern" => "^[A-Za-z][A-Za-z0-9-]{0,31}$" },
+            "maximum_bytes_billed" => {
+              "type" => "integer", "minimum" => 1, "maximum" => 10_000_000_000_000_000
+            },
+            "experimental" => { "const" => true }
+          }
+        },
+        "funnelStep" => {
+          "type" => "object", "additionalProperties" => false, "required" => %w[name event_name],
+          "properties" => {
+            "name" => { "type" => "string", "minLength" => 1, "maxLength" => 64 },
+            "event_name" => { "type" => "string", "pattern" => "^[A-Za-z][A-Za-z0-9_]{0,39}$" }
+          }
+        },
+        "funnel" => {
+          "type" => "object", "additionalProperties" => false, "required" => %w[steps experimental],
+          "properties" => {
+            "steps" => {
+              "type" => "array", "minItems" => 2, "maxItems" => 10,
+              "items" => { "$ref" => "#/$defs/funnelStep" }
+            },
+            "experimental" => { "const" => true }
+          }
+        },
+        "funnels" => {
+          "type" => "object", "maxProperties" => 20,
+          "propertyNames" => { "pattern" => "^[A-Za-z][A-Za-z0-9_]{0,63}$" },
+          "additionalProperties" => { "$ref" => "#/$defs/funnel" }
         }
       }
     )

data/lib/analytics_ops/configuration/validator.rb

@@ -3,6 +3,8 @@
 # Strict configuration validation.
 
 require "uri"
+require_relative "validator_experimental"
+require_relative "validator_reporting"
 
 module AnalyticsOps
   module Configuration
@@ -10,7 +12,22 @@ module AnalyticsOps
     class Validator
       TOP_LEVEL_KEYS = %w[version profiles].freeze
       PROFILE_KEYS = %w[property_id streams retention google_signals key_events custom_dimensions custom_metrics
-                        manual_requirements].freeze
+                        manual_requirements labels reports health funnels bigquery governance].freeze
+      REPORT_KEYS = %w[
+        kind dimensions metrics date_ranges dimension_filter metric_filter order_bys limit
+      ].freeze
+      HEALTH_KEYS = %w[
+        expected_events minimum_sessions traffic_drop_percent key_event_drop_percent
+        unassigned_percent not_set_percent
+      ].freeze
+      GOVERNANCE_KEYS = %w[
+        enhanced_measurement_required email_redaction_required query_parameter_redaction_required
+        reporting_identity bigquery_link_required expected_channel_groups expected_calculated_metrics
+        expected_event_create_rules expected_event_edit_rules experimental
+      ].freeze
+      BIGQUERY_KEYS = %w[project_id dataset location maximum_bytes_billed experimental].freeze
+      FUNNEL_KEYS = %w[steps experimental].freeze
+      FUNNEL_STEP_KEYS = %w[name event_name].freeze
       STREAM_KEYS = %w[stream_id default_uri enhanced_measurement].freeze
       ENHANCED_MEASUREMENT_KEYS = %w[enabled experimental].freeze
       RETENTION_KEYS = %w[event_data user_data reset_on_new_activity].freeze
@@ -77,7 +94,13 @@ module AnalyticsOps
           custom_dimensions: validate_dimensions(profile.fetch("custom_dimensions", []), path),
           custom_metrics: validate_metrics(profile.fetch("custom_metrics", []), path),
           manual_requirements: validate_manual_requirements(profile.fetch("manual_requirements", []), path),
-          google_signals: validate_google_signals(profile["google_signals"], path)
+          google_signals: validate_google_signals(profile["google_signals"], path),
+          labels: validate_labels(profile.fetch("labels", {}), path),
+          reports: validate_reports(profile.fetch("reports", {}), path),
+          health: validate_health(profile["health"], path),
+          governance: validate_governance(profile["governance"], path),
+          bigquery: validate_bigquery(profile["bigquery"], path),
+          funnels: validate_funnels(profile.fetch("funnels", {}), path)
         )
       end
 
@@ -96,7 +119,7 @@ module AnalyticsOps
             "enhanced_measurement" => validate_enhanced_measurement(stream["enhanced_measurement"], stream_path)
           }
         end
-        streams.sort_by { |stream| stream.fetch("name") }
+        ensure_unique!(streams, ["stream_id"], path).sort_by { |stream| stream.fetch("name") }
       end
 
       def validate_enhanced_measurement(raw, stream_path)
@@ -140,11 +163,13 @@ module AnalyticsOps
 
       def validate_key_events(raw, profile_path)
         path = "#{profile_path}.key_events"
+        validate_event_names(raw, path)
+      end
+
+      def validate_event_names(raw, path)
         values = array!(raw, path).map.with_index do |event_name, index|
-          string = string!(event_name, "#{profile_path}.key_events[#{index}]")
-          unless EVENT_NAME.match?(string)
-            raise ConfigurationError, "#{profile_path}.key_events[#{index}] is not a valid GA4 event name"
-          end
+          string = string!(event_name, "#{path}[#{index}]")
+          raise ConfigurationError, "#{path}[#{index}] is not a valid GA4 event name" unless EVENT_NAME.match?(string)
 
           string
         end
@@ -354,6 +379,19 @@ module AnalyticsOps
         raise ConfigurationError, "#{path} must be true or false"
       end
 
+      def integer!(value, path, minimum:, maximum:)
+        return value if value.is_a?(Integer) && value.between?(minimum, maximum)
+
+        raise ConfigurationError, "#{path} must be an integer between #{minimum} and #{maximum}"
+      end
+
+      def percentage!(value, path)
+        valid = (value.is_a?(Integer) || value.is_a?(Float)) && value.finite? && value.between?(0, 100)
+        return value.to_f if valid
+
+        raise ConfigurationError, "#{path} must be a finite number between 0 and 100"
+      end
+
       def id!(value, path)
         string = string!(value, path)
         raise ConfigurationError, "#{path} must be a numeric identifier encoded as a string" unless ID.match?(string)

data/lib/analytics_ops/configuration/validator_experimental.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module AnalyticsOps
+  module Configuration
+    # Reopens the strict validator to add opt-in feature validation.
+    class Validator
+      # Validation for opt-in BigQuery, funnel, and governance features.
+      module ExperimentalValidation
+        private
+
+        def validate_funnels(raw, profile_path)
+          path = "#{profile_path}.funnels"
+          funnels = hash!(raw, path)
+          raise ConfigurationError, "#{path} can contain at most 20 funnels" if funnels.length > 20
+
+          funnels.sort.to_h do |name, value|
+            validate_name!(name, "#{path} key")
+            item_path = "#{path}.#{name}"
+            funnel = hash!(value, item_path)
+            exact_keys!(funnel, FUNNEL_KEYS, item_path)
+            unless boolean!(required(funnel, "experimental", item_path), "#{item_path}.experimental")
+              raise ConfigurationError, "#{item_path}.experimental must be true"
+            end
+
+            [name, validated_funnel(name, funnel, item_path)]
+          rescue InvalidRequestError => error
+            raise ConfigurationError, "#{item_path}: #{error.message}"
+          end
+        end
+
+        def validated_funnel(name, funnel, item_path)
+          raw_steps = array!(required(funnel, "steps", item_path), "#{item_path}.steps")
+          steps = raw_steps.map.with_index do |step, index|
+            step_path = "#{item_path}.steps[#{index}]"
+            value = hash!(step, step_path)
+            exact_keys!(value, FUNNEL_STEP_KEYS, step_path)
+            {
+              "name" => string!(required(value, "name", step_path), "#{step_path}.name"),
+              "event_name" => string!(required(value, "event_name", step_path), "#{step_path}.event_name")
+            }
+          end
+          Funnels::Definition.new(name:, steps:)
+        end
+
+        def validate_bigquery(raw, profile_path)
+          return nil if raw.nil?
+
+          path = "#{profile_path}.bigquery"
+          settings = hash!(raw, path)
+          exact_keys!(settings, BIGQUERY_KEYS, path)
+          unless boolean!(required(settings, "experimental", path), "#{path}.experimental")
+            raise ConfigurationError, "#{path}.experimental must be true"
+          end
+
+          project_id = string!(required(settings, "project_id", path), "#{path}.project_id")
+          dataset = string!(required(settings, "dataset", path), "#{path}.dataset")
+          location = string!(settings.fetch("location", "US"), "#{path}.location")
+          validate_bigquery_names!(project_id, dataset, location, path)
+          {
+            "project_id" => project_id,
+            "dataset" => dataset,
+            "location" => location,
+            "maximum_bytes_billed" => integer!(
+              required(settings, "maximum_bytes_billed", path),
+              "#{path}.maximum_bytes_billed",
+              minimum: 1,
+              maximum: 10_000_000_000_000_000
+            ),
+            "experimental" => true
+          }
+        end
+
+        def validate_bigquery_names!(project_id, dataset, location, path)
+          unless project_id.match?(/\A[a-z][a-z0-9-]{4,28}[a-z0-9]\z/)
+            raise ConfigurationError, "#{path}.project_id is invalid"
+          end
+          unless dataset.match?(/\A[A-Za-z_][A-Za-z0-9_]{0,1023}\z/)
+            raise ConfigurationError, "#{path}.dataset is invalid"
+          end
+          return if location.match?(/\A[A-Za-z][A-Za-z0-9-]{0,31}\z/)
+
+          raise ConfigurationError, "#{path}.location is invalid"
+        end
+
+        def validate_governance(raw, profile_path)
+          return nil if raw.nil?
+
+          path = "#{profile_path}.governance"
+          settings = hash!(raw, path)
+          exact_keys!(settings, GOVERNANCE_KEYS, path)
+          unless boolean!(required(settings, "experimental", path), "#{path}.experimental")
+            raise ConfigurationError, "#{path}.experimental must be true"
+          end
+
+          governance_settings(settings, path)
+        end
+
+        def governance_settings(settings, path)
+          result = { "experimental" => true }
+          %w[
+            enhanced_measurement_required email_redaction_required
+            query_parameter_redaction_required bigquery_link_required
+          ].each { |name| result[name] = boolean!(settings.fetch(name, false), "#{path}.#{name}") }
+          if settings.key?("reporting_identity")
+            result["reporting_identity"] = enum!(
+              settings.fetch("reporting_identity"),
+              %w[blended observed device_based],
+              "#{path}.reporting_identity"
+            )
+          end
+          %w[
+            expected_channel_groups expected_calculated_metrics
+            expected_event_create_rules expected_event_edit_rules
+          ].each do |name|
+            result[name] = printable_string_array(settings.fetch(name, []), "#{path}.#{name}")
+          end
+          result
+        end
+
+        def printable_string_array(raw, path)
+          values = array!(raw, path).map.with_index do |value, index|
+            string = string!(value, "#{path}[#{index}]")
+            unless !string.empty? && string.length <= 128 && !string.match?(/[\u0000-\u001f\u007f]/)
+              raise ConfigurationError, "#{path}[#{index}] must be a printable string of at most 128 characters"
+            end
+
+            string
+          end
+          ensure_unique_strings!(values, path)
+        end
+      end
+
+      include ExperimentalValidation
+    end
+  end
+end

data/lib/analytics_ops/configuration/validator_reporting.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module AnalyticsOps
+  module Configuration
+    # Reopens the strict validator to add reporting configuration validation.
+    class Validator
+      # Validation for health settings, labels, and user-defined reports.
+      module ReportingValidation
+        private
+
+        def validate_health(raw, profile_path)
+          return nil if raw.nil?
+
+          path = "#{profile_path}.health"
+          health = hash!(raw, path)
+          exact_keys!(health, HEALTH_KEYS, path)
+          defaults = Health::DEFAULTS
+          {
+            "expected_events" => validate_event_names(
+              health.fetch("expected_events", defaults.fetch("expected_events")),
+              "#{path}.expected_events"
+            ),
+            "minimum_sessions" => integer!(
+              health.fetch("minimum_sessions", defaults.fetch("minimum_sessions")),
+              "#{path}.minimum_sessions", minimum: 0, maximum: 1_000_000_000
+            ),
+            "traffic_drop_percent" => percentage_setting(health, defaults, "traffic_drop_percent", path),
+            "key_event_drop_percent" => percentage_setting(health, defaults, "key_event_drop_percent", path),
+            "unassigned_percent" => percentage_setting(health, defaults, "unassigned_percent", path),
+            "not_set_percent" => percentage_setting(health, defaults, "not_set_percent", path)
+          }
+        end
+
+        def percentage_setting(settings, defaults, name, path)
+          percentage!(settings.fetch(name, defaults.fetch(name)), "#{path}.#{name}")
+        end
+
+        def validate_labels(raw, profile_path)
+          path = "#{profile_path}.labels"
+          labels = hash!(raw, path)
+          raise ConfigurationError, "#{path} can contain at most 16 labels" if labels.length > 16
+
+          labels.sort.to_h do |name, value|
+            validate_name!(name, "#{path} key")
+            label = string!(value, "#{path}.#{name}")
+            unless !label.empty? && label.length <= 64 && !label.match?(/[\u0000-\u001f\u007f]/)
+              raise ConfigurationError, "#{path}.#{name} must be a printable string of at most 64 characters"
+            end
+
+            [name, label]
+          end
+        end
+
+        def validate_reports(raw, profile_path)
+          path = "#{profile_path}.reports"
+          reports = hash!(raw, path)
+          raise ConfigurationError, "#{path} can contain at most 50 reports" if reports.length > 50
+
+          reports.sort.to_h do |name, value|
+            validate_name!(name, "#{path} key")
+            item_path = "#{path}.#{name}"
+            report = hash!(value, item_path)
+            exact_keys!(report, REPORT_KEYS, item_path)
+            [name, configured_report(name, report, item_path)]
+          rescue InvalidRequestError => error
+            raise ConfigurationError, "#{item_path}: #{error.message}"
+          end
+        end
+
+        def configured_report(name, report, item_path)
+          kind = enum!(report.fetch("kind", "standard"), Reports::Definition::KINDS, "#{item_path}.kind")
+          date_ranges = report.fetch(
+            "date_ranges",
+            kind == "standard" ? Reports::Catalog::STANDARD_DATE_RANGE : []
+          )
+          Reports::Definition.new(
+            name:,
+            kind:,
+            dimensions: report.fetch("dimensions", []),
+            metrics: required(report, "metrics", item_path),
+            date_ranges:,
+            dimension_filter: report["dimension_filter"],
+            metric_filter: report["metric_filter"],
+            order_bys: report.fetch("order_bys", []),
+            limit: report.fetch("limit", 100)
+          )
+        end
+      end
+
+      include ReportingValidation
+    end
+  end
+end