analytics_ops 0.1.0

data/lib/analytics_ops/planner.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+# Deterministic read-only planning.
+
+module AnalyticsOps
+  # Pure desired-vs-remote comparison. It never owns or contacts a client.
+  class Planner
+    def initialize(desired_state:, snapshot:)
+      @desired = desired_state
+      @snapshot = snapshot
+      @changes = []
+      @findings = []
+    end
+
+    def call
+      unless @desired.property_id == @snapshot.property_id
+        raise ConflictError,
+              "Configured property #{@desired.property_id} does not match snapshot #{@snapshot.property_id}"
+      end
+
+      plan_streams
+      plan_retention
+      plan_key_events
+      plan_custom_dimensions
+      plan_custom_metrics
+      add_manual_findings
+      add_experimental_findings
+
+      Plan.new(
+        profile: @desired.profile,
+        property_id: @desired.property_id,
+        snapshot_fingerprint: @snapshot.fingerprint,
+        changes: @changes,
+        findings: @findings
+      )
+    end
+
+    private
+
+    def plan_streams
+      remote = unique_index(@snapshot.streams, "data stream", &:id)
+      @desired.streams.each { |desired| plan_stream(remote, desired) }
+    end
+
+    def plan_stream(remote, desired)
+      stream = remote[desired.fetch("stream_id")]
+      identity = "stream:#{desired.fetch("stream_id")}"
+      unless stream
+        finding("drift", "missing_stream", identity,
+                "Configured data stream is not accessible; stream creation is not automatic")
+        return
+      end
+
+      plan_stream_uri(stream, desired, identity)
+      return unless desired["enhanced_measurement"]
+
+      finding(
+        "experimental",
+        "enhanced_measurement_not_managed",
+        identity,
+        "Enhanced Measurement is declared but remains an experimental, non-applicable capability"
+      )
+    end
+
+    def plan_stream_uri(stream, desired, identity)
+      return unless desired["default_uri"] && stream.default_uri != desired["default_uri"]
+
+      if stream.type == "web"
+        update(
+          "data_stream",
+          identity,
+          stream.to_h,
+          stream.to_h.merge("default_uri" => desired.fetch("default_uri")),
+          rollback: "Restore the previous web stream default URI"
+        )
+      else
+        finding("drift", "non_web_default_uri", identity, "Only web streams have a configurable default URI")
+      end
+    end
+
+    def plan_retention
+      desired = @desired.retention
+      return unless desired
+
+      remote = @snapshot.retention
+      unless remote
+        finding("drift", "retention_unavailable", "property:#{@desired.property_id}:retention",
+                "Data retention settings could not be discovered")
+        return
+      end
+
+      current = remote.to_h
+      after = current.merge(desired)
+      return if equivalent?(current, after, %w[event_data user_data reset_on_new_activity])
+
+      update(
+        "retention",
+        "property:#{@desired.property_id}:retention",
+        current,
+        after,
+        rollback: "Restore the previous event and user retention durations and reset behavior"
+      )
+    end
+
+    def plan_key_events
+      remote = unique_index(@snapshot.key_events, "key event", &:event_name)
+      @desired.key_events.each do |event_name|
+        next if remote.key?(event_name)
+
+        create(
+          "key_event",
+          "event:#{event_name}",
+          { "event_name" => event_name, "counting_method" => "once_per_event" },
+          rollback: "Delete the newly created key event in Google Analytics if rollback is required"
+        )
+      end
+    end
+
+    def plan_custom_dimensions
+      remote = unique_index(@snapshot.custom_dimensions, "custom dimension") do |dimension|
+        [dimension.scope, dimension.parameter_name]
+      end
+
+      @desired.custom_dimensions.each do |desired|
+        identity_key = [desired.fetch("scope"), desired.fetch("parameter_name")]
+        identity = identity_key.join(":").to_s
+        current = remote[identity_key]
+        unless current
+          create("custom_dimension", identity, desired, rollback: "Archive the newly created custom dimension")
+          next
+        end
+
+        before = current.to_h
+        mutable = %w[display_name description]
+        mutable << "disallow_ads_personalization" if desired.fetch("scope") == "user"
+        after = before.merge(desired.slice(*mutable))
+        next if equivalent?(before, after, mutable)
+
+        update("custom_dimension", identity, before, after, rollback: "Restore the previous custom dimension metadata")
+      end
+    end
+
+    def plan_custom_metrics
+      remote = unique_index(@snapshot.custom_metrics, "custom metric", &:parameter_name)
+
+      @desired.custom_metrics.each do |desired|
+        identity = desired.fetch("parameter_name")
+        current = remote[identity]
+        unless current
+          create("custom_metric", identity, desired, rollback: "Archive the newly created custom metric")
+          next
+        end
+
+        before = current.to_h
+        if before.fetch("scope") != desired.fetch("scope") ||
+           before.fetch("measurement_unit") != desired.fetch("measurement_unit")
+          finding("drift", "immutable_metric_conflict", "metric:#{identity}",
+                  "Custom metric scope or measurement unit differs and will not be recreated automatically")
+          next
+        end
+
+        mutable = %w[display_name description]
+        after = before.merge(desired.slice(*mutable))
+        next if equivalent?(before, after, mutable)
+
+        update("custom_metric", identity, before, after, rollback: "Restore the previous custom metric metadata")
+      end
+    end
+
+    def add_manual_findings
+      @desired.manual_requirements.each do |requirement|
+        finding("manual", "manual_requirement", requirement, "Verify #{requirement.tr("_", " ")} in Google Analytics")
+      end
+    end
+
+    def add_experimental_findings
+      return unless @desired.google_signals
+
+      finding(
+        "experimental",
+        "google_signals_not_managed",
+        "property:#{@desired.property_id}:google_signals",
+        "Google Signals is declared but remains an experimental, non-applicable capability"
+      )
+    end
+
+    def create(resource_type, identity, after, rollback:)
+      @changes << Plan::Change.new(
+        resource_type:,
+        resource_identity: identity,
+        operation: "create",
+        api_maturity: "beta",
+        before: nil,
+        after: Canonical.normalize(after),
+        reversible: true,
+        rollback:
+      )
+    end
+
+    def update(resource_type, identity, before, after, rollback:)
+      @changes << Plan::Change.new(
+        resource_type:,
+        resource_identity: identity,
+        operation: "update",
+        api_maturity: "beta",
+        before: Canonical.normalize(before),
+        after: Canonical.normalize(after),
+        reversible: true,
+        rollback:
+      )
+    end
+
+    def finding(severity, code, identity, message)
+      @findings << Plan::Finding.new(severity:, code:, resource_identity: identity, message:)
+    end
+
+    def unique_index(values, resource)
+      values.each_with_object({}) do |value, result|
+        identity = yield(value)
+        if result.key?(identity)
+          raise ConflictError,
+                "Ambiguous remote #{resource} identity #{Array(identity).join(":")}"
+        end
+
+        result[identity] = value
+      end
+    end
+
+    def equivalent?(before, after, keys)
+      keys.all? { |key| before[key] == after[key] }
+    end
+  end
+end

data/lib/analytics_ops/rails/railtie.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module AnalyticsOps
+  # Helpers used only when an operator explicitly invokes a Rails Rake task.
+  module RailsTasks
+    module_function
+
+    def run(command, report_name: nil)
+      arguments = [
+        command,
+        "--config", ENV.fetch("ANALYTICS_OPS_CONFIG", Rails.root.join("config/analytics_ops.yml").to_s),
+        "--profile", ENV.fetch("ANALYTICS_OPS_PROFILE", Rails.env.to_s)
+      ]
+      if command == "plan"
+        arguments.push("--output",
+                       ENV.fetch("ANALYTICS_OPS_PLAN", Rails.root.join("tmp/analytics_ops-plan.json").to_s))
+      end
+      arguments << report_name if report_name
+
+      status = CLI.start(arguments)
+      return if status == CLI::SUCCESS
+
+      raise Error, "analytics-ops #{command} exited with status #{status}"
+    end
+  end
+
+  # Optional Rails hooks. Defining this class performs no Google API calls.
+  class Railtie < Rails::Railtie
+    generators do
+      require_relative "../../generators/analytics_ops/install_generator"
+    end
+
+    rake_tasks do
+      namespace :analytics do
+        desc "Validate Analytics Ops configuration, credentials, and API access"
+        task doctor: :environment do
+          RailsTasks.run("doctor")
+        end
+
+        desc "Audit configured Google Analytics state without changing it"
+        task audit: :environment do
+          RailsTasks.run("audit")
+        end
+
+        desc "Write a deterministic Analytics Ops plan"
+        task plan: :environment do
+          RailsTasks.run("plan")
+        end
+
+        desc "Verify that managed Google Analytics state converges"
+        task verify: :environment do
+          RailsTasks.run("verify")
+        end
+
+        desc "Run a built-in report: rake analytics:report[NAME]"
+        task :report, [:name] => :environment do |_task, arguments|
+          name = arguments[:name]
+          raise Error, "analytics:report requires NAME" if name.to_s.empty?
+
+          RailsTasks.run("report", report_name: name)
+        end
+      end
+    end
+  end
+end

data/lib/analytics_ops/rails.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "../analytics_ops"
+require "rails/railtie"
+require_relative "rails/railtie"

data/lib/analytics_ops/redaction.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "json"
+
+module AnalyticsOps
+  # Removes credential-shaped material before text reaches user-visible output.
+  module Redaction
+    BEARER = /\bBearer\s+[^\s,;]+/i
+    AUTHORIZATION = /\bAuthorization\s*[:=]\s*[^\r\n,;]+/i
+    PRIVATE_KEY = /-----BEGIN[^-]*PRIVATE KEY-----.*?-----END[^-]*PRIVATE KEY-----/mi
+    SECRET_ASSIGNMENT = /
+      (
+        access[_ -]?token|refresh[_ -]?token|client[_ -]?(?:id|secret)|
+        private[_ -]?key|password|api[_ -]?key|credentials?
+      )
+      \s*([:=]\s*|=>\s*)["']?[^\s,"';}]+
+    /ix
+    CONTROL_CHARACTERS = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/
+
+    module_function
+
+    def message(value)
+      value.to_s
+           .gsub(PRIVATE_KEY, "[REDACTED]")
+           .gsub(AUTHORIZATION, "Authorization: [REDACTED]")
+           .gsub(BEARER, "Bearer [REDACTED]")
+           .gsub(SECRET_ASSIGNMENT) { "#{Regexp.last_match(1)}=[REDACTED]" }
+           .gsub(CONTROL_CHARACTERS, "?")
+           .slice(0, 1_000)
+    end
+  end
+
+  # Writes small structured operational events without requests, responses, or credentials.
+  module SafeLogging
+    module_function
+
+    def write(logger, level, event, details = {})
+      return unless logger.respond_to?(level)
+
+      payload = { "source" => "analytics_ops", "event" => event }.merge(details)
+      logger.public_send(level, Redaction.message(JSON.generate(payload)))
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/analytics_ops/reports/catalog.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module AnalyticsOps
+  module Reports
+    # Small built-in catalog focused on acquisition and calculator outcomes.
+    module Catalog
+      STANDARD_DATE_RANGE = [{ "start_date" => "28daysAgo", "end_date" => "yesterday" }].freeze
+      CALCULATOR = "customEvent:calculator_slug"
+      EVENT_FILTER = lambda do |value, match_type = "exact"|
+        { "field" => "eventName", "match_type" => match_type, "value" => value }
+      end
+
+      DEFINITIONS = [
+        Definition.new(
+          name: "traffic_acquisition",
+          kind: "standard",
+          dimensions: %w[sessionDefaultChannelGroup sessionSource sessionMedium],
+          metrics: %w[sessions totalUsers keyEvents],
+          date_ranges: STANDARD_DATE_RANGE,
+          order_bys: [{ "metric" => "sessions", "desc" => true }],
+          limit: 250
+        ),
+        Definition.new(
+          name: "landing_pages",
+          kind: "standard",
+          dimensions: %w[landingPagePlusQueryString],
+          metrics: %w[sessions totalUsers keyEvents],
+          date_ranges: STANDARD_DATE_RANGE,
+          order_bys: [{ "metric" => "sessions", "desc" => true }],
+          limit: 500
+        ),
+        Definition.new(
+          name: "calculator_completions",
+          kind: "standard",
+          dimensions: ["eventName", CALCULATOR],
+          metrics: %w[eventCount totalUsers],
+          date_ranges: STANDARD_DATE_RANGE,
+          dimension_filter: EVENT_FILTER.call("calculation_completed"),
+          order_bys: [{ "metric" => "eventCount", "desc" => true }],
+          limit: 500
+        ),
+        Definition.new(
+          name: "shares_and_prints",
+          kind: "standard",
+          dimensions: ["eventName", CALCULATOR],
+          metrics: %w[eventCount totalUsers],
+          date_ranges: STANDARD_DATE_RANGE,
+          dimension_filter: EVENT_FILTER.call("^(result_shared|result_printed)$", "full_regexp"),
+          order_bys: [{ "metric" => "eventCount", "desc" => true }],
+          limit: 500
+        ),
+        Definition.new(
+          name: "related_calculator_navigation",
+          kind: "standard",
+          dimensions: ["eventName", CALCULATOR, "customEvent:related_calculator_slug"],
+          metrics: %w[eventCount totalUsers],
+          date_ranges: STANDARD_DATE_RANGE,
+          dimension_filter: EVENT_FILTER.call("related_calculator_clicked"),
+          order_bys: [{ "metric" => "eventCount", "desc" => true }],
+          limit: 500
+        ),
+        Definition.new(
+          name: "commercial_outbound_clicks",
+          kind: "standard",
+          dimensions: ["eventName", CALCULATOR, "customEvent:outbound_destination"],
+          metrics: %w[eventCount totalUsers],
+          date_ranges: STANDARD_DATE_RANGE,
+          dimension_filter: EVENT_FILTER.call("commercial_outbound_clicked"),
+          order_bys: [{ "metric" => "eventCount", "desc" => true }],
+          limit: 500
+        ),
+        Definition.new(
+          name: "realtime_events",
+          kind: "realtime",
+          dimensions: %w[eventName],
+          metrics: %w[eventCount activeUsers],
+          order_bys: [{ "metric" => "eventCount", "desc" => true }],
+          limit: 100
+        )
+      ].to_h { |definition| [definition.name, definition] }.freeze
+
+      module_function
+
+      def fetch(name, kind: nil)
+        definition = DEFINITIONS.fetch(name.to_s) do
+          raise InvalidRequestError, "Unknown report #{name.inspect}; available reports: #{names.join(", ")}"
+        end
+        if kind && definition.kind != kind.to_s
+          raise InvalidRequestError, "Report #{name} is #{definition.kind}, not #{kind}"
+        end
+
+        definition
+      end
+
+      def names
+        DEFINITIONS.keys.sort
+      end
+    end
+  end
+end

data/lib/analytics_ops/reports/definition.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require "date"
+
+module AnalyticsOps
+  module Reports
+    # Immutable, gem-owned description of one Data API query.
+    class Definition
+      KINDS = %w[standard realtime].freeze
+      API_NAME = /\A[a-z][a-zA-Z0-9_]*(?::[a-zA-Z][a-zA-Z0-9_]*)?\z/
+      REPORT_NAME = /\A[a-z][a-z0-9_]{0,63}\z/
+      RANGE_NAME = /\A[a-z][a-z0-9_]{0,39}\z/
+      RELATIVE_DATE = /\A(\d{1,4})daysAgo\z/
+      MATCH_TYPES = %w[exact begins_with ends_with contains full_regexp partial_regexp].freeze
+      NUMERIC_OPERATIONS = %w[equal less_than less_than_or_equal greater_than greater_than_or_equal].freeze
+      MAX_LIMIT = 100_000
+
+      attr_reader :name, :kind, :dimensions, :metrics, :date_ranges,
+                  :dimension_filter, :metric_filter, :order_bys, :offset, :limit
+
+      def initialize(name:, kind:, dimensions:, metrics:, date_ranges: [], dimension_filter: nil,
+                     metric_filter: nil, order_bys: [], offset: 0, limit: 100)
+        @name = validate_name(name)
+        @kind = validate_kind(kind)
+        @dimensions = api_names(dimensions, "dimensions", maximum: realtime_kind?(kind) ? 4 : 9)
+        @metrics = api_names(metrics, "metrics", maximum: 10)
+        @date_ranges = ranges(date_ranges)
+        @dimension_filter = string_filter(dimension_filter)
+        @metric_filter = numeric_filter(metric_filter)
+        @order_bys = orders(order_bys)
+        @offset = integer(offset, "offset", minimum: 0, maximum: 1_000_000_000)
+        @limit = integer(limit, "limit", minimum: 1, maximum: MAX_LIMIT)
+        validate_shape!
+        freeze
+      end
+
+      def realtime?
+        kind == "realtime"
+      end
+
+      def to_h
+        {
+          "name" => name,
+          "kind" => kind,
+          "dimensions" => dimensions,
+          "metrics" => metrics,
+          "date_ranges" => date_ranges,
+          "dimension_filter" => dimension_filter,
+          "metric_filter" => metric_filter,
+          "order_bys" => order_bys,
+          "offset" => offset,
+          "limit" => limit
+        }
+      end
+
+      private
+
+      def validate_name(value)
+        return value.dup.freeze if value.is_a?(String) && REPORT_NAME.match?(value)
+
+        raise InvalidRequestError, "Report name is invalid"
+      end
+
+      def validate_kind(value)
+        return value.dup.freeze if value.is_a?(String) && KINDS.include?(value)
+
+        raise InvalidRequestError, "Report kind must be standard or realtime"
+      end
+
+      def realtime_kind?(value)
+        value == "realtime"
+      end
+
+      def api_names(values, label, maximum:)
+        unless values.is_a?(Array) && values.any? && values.length <= maximum &&
+               values.all? { |value| valid_api_name?(value) }
+          raise InvalidRequestError, "Report #{label} must contain 1 to #{maximum} valid Data API names"
+        end
+        unless values.uniq.length == values.length
+          raise InvalidRequestError,
+                "Report #{label} must not contain duplicates"
+        end
+
+        Canonical.immutable(values)
+      end
+
+      def valid_api_name?(value)
+        value.is_a?(String) && value.length <= 128 && API_NAME.match?(value)
+      end
+
+      def ranges(values)
+        raise InvalidRequestError, "date_ranges must be an array" unless values.is_a?(Array)
+        raise InvalidRequestError, "A report can contain at most four date ranges" if values.length > 4
+
+        normalized = values.map do |range|
+          hash = string_hash(range, "date range", %w[start_date end_date name])
+          start_date = date(hash.fetch("start_date") { invalid!("Missing start_date") })
+          end_date = date(hash.fetch("end_date") { invalid!("Missing end_date") })
+          validate_date_order!(start_date, end_date)
+
+          result = { "start_date" => start_date, "end_date" => end_date }
+          if hash.key?("name")
+            range_name = hash.fetch("name")
+            invalid!("Date range name is invalid") unless range_name.is_a?(String) && RANGE_NAME.match?(range_name)
+            result["name"] = range_name
+          end
+          result
+        end
+        Canonical.immutable(normalized)
+      end
+
+      def date(value)
+        invalid!("Invalid report date") unless value.is_a?(String)
+        return value if %w[today yesterday].include?(value)
+
+        relative = RELATIVE_DATE.match(value)
+        return value if relative && relative[1].to_i <= 3650
+
+        Date.iso8601(value)
+        value
+      rescue Date::Error
+        invalid!("Invalid report date")
+      end
+
+      def validate_date_order!(start_date, end_date)
+        return unless start_date.match?(/\A\d{4}-/) && end_date.match?(/\A\d{4}-/)
+        return if Date.iso8601(start_date) <= Date.iso8601(end_date)
+
+        invalid!("Report start_date must not be after end_date")
+      end
+
+      def string_filter(value)
+        return nil if value.nil?
+
+        hash = string_hash(value, "dimension filter", %w[field match_type value case_sensitive])
+        field = hash.fetch("field") { invalid!("Missing filter field") }
+        match_type = hash.fetch("match_type") { invalid!("Missing filter match_type") }
+        filter_value = hash.fetch("value") { invalid!("Missing filter value") }
+        unless valid_api_name?(field) && dimensions.include?(field) && MATCH_TYPES.include?(match_type) &&
+               printable_string?(filter_value, maximum: 1_024)
+          invalid!("Dimension filter is invalid or references an unselected dimension")
+        end
+
+        case_sensitive = hash.key?("case_sensitive") ? boolean(hash.fetch("case_sensitive"), "case_sensitive") : false
+        Canonical.immutable(
+          "field" => field,
+          "match_type" => match_type,
+          "value" => filter_value,
+          "case_sensitive" => case_sensitive
+        )
+      end
+
+      def numeric_filter(value)
+        return nil if value.nil?
+
+        hash = string_hash(value, "metric filter", %w[field operation value])
+        field = hash.fetch("field") { invalid!("Missing metric filter field") }
+        operation = hash.fetch("operation") { invalid!("Missing metric filter operation") }
+        number = hash.fetch("value") { invalid!("Missing metric filter value") }
+        valid = valid_api_name?(field) && metrics.include?(field) &&
+                NUMERIC_OPERATIONS.include?(operation) && number.is_a?(Numeric)
+        invalid!("Metric filter is invalid or references an unselected metric") unless valid
+        invalid!("Metric filter value must be finite") unless number.finite?
+
+        Canonical.immutable("field" => field, "operation" => operation, "value" => number)
+      end
+
+      def orders(values)
+        raise InvalidRequestError, "order_bys must be an array" unless values.is_a?(Array)
+        raise InvalidRequestError, "A report can contain at most ten order clauses" if values.length > 10
+
+        normalized = values.map do |order|
+          hash = string_hash(order, "report order", %w[metric dimension desc])
+          selectors = %w[metric dimension].select { |key| hash.key?(key) }
+          invalid!("Report order requires exactly one metric or dimension") unless selectors.length == 1
+
+          selector = selectors.first
+          api_name = hash.fetch(selector)
+          selected = selector == "metric" ? metrics : dimensions
+          unless valid_api_name?(api_name) && selected.include?(api_name)
+            invalid!("Report order references an unselected #{selector}")
+          end
+
+          { selector => api_name, "desc" => hash.key?("desc") ? boolean(hash.fetch("desc"), "desc") : false }
+        end
+        Canonical.immutable(normalized)
+      end
+
+      def validate_shape!
+        invalid!("Realtime reports cannot include date ranges") if realtime? && !date_ranges.empty?
+        invalid!("Realtime reports do not support offset") if realtime? && offset.positive?
+        invalid!("Standard reports require a date range") if !realtime? && date_ranges.empty?
+      end
+
+      def string_hash(value, label, allowed)
+        raise InvalidRequestError, "#{label} must be an object" unless value.is_a?(Hash)
+        raise InvalidRequestError, "#{label} keys must be strings" unless value.keys.all?(String)
+
+        unknown = value.keys - allowed
+        raise InvalidRequestError, "Unknown #{label} field #{unknown.first}" unless unknown.empty?
+
+        value
+      end
+
+      def printable_string?(value, maximum:)
+        value.is_a?(String) && !value.empty? && value.length <= maximum && !value.match?(/[\u0000-\u001f\u007f]/)
+      end
+
+      def boolean(value, label)
+        return value if [true, false].include?(value)
+
+        raise InvalidRequestError, "#{label} must be true or false"
+      end
+
+      def integer(value, label, minimum:, maximum:)
+        return value if value.is_a?(Integer) && value.between?(minimum, maximum)
+
+        raise InvalidRequestError, "Report #{label} must be between #{minimum} and #{maximum}"
+      end
+
+      def invalid!(message)
+        raise InvalidRequestError, message
+      end
+    end
+  end
+end