analytics_ops 0.2.0 → 0.3.0

data/lib/analytics_ops/health.rb

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module AnalyticsOps
+  # Deterministic, read-only analytics quality checks.
+  module Health
+    DEFAULTS = Canonical.deep_freeze(
+      "expected_events" => [],
+      "minimum_sessions" => 1,
+      "traffic_drop_percent" => 50.0,
+      "key_event_drop_percent" => 50.0,
+      "unassigned_percent" => 20.0,
+      "not_set_percent" => 20.0
+    )
+
+    module_function
+
+    def validate_date_ranges!(value)
+      valid = value.is_a?(Array) &&
+              value.length == 2 &&
+              value.all? { |range| range.is_a?(Hash) && range.keys.all?(String) } &&
+              value.map { |range| range["name"] } == %w[current previous]
+      return value if valid
+
+      raise InvalidRequestError, "Health requires current and previous comparison date ranges"
+    end
+
+    # One deterministic analytics health observation.
+    class Finding < Resources::Value
+      fields :severity, :code, :message, :actual, :expected
+    end
+
+    # Immutable health summary and findings for one profile.
+    class Result
+      attr_reader :profile, :property_id, :date_ranges, :findings, :summary
+
+      def initialize(profile:, property_id:, date_ranges:, findings:, summary:)
+        @profile = Canonical.immutable(profile)
+        @property_id = Canonical.immutable(property_id)
+        @date_ranges = Canonical.immutable(date_ranges)
+        @findings = findings.dup.freeze
+        @summary = Canonical.immutable(summary)
+        freeze
+      end
+
+      def healthy?
+        findings.none? { |finding| %w[warning error].include?(finding.severity) }
+      end
+
+      def to_h
+        {
+          "healthy" => healthy?,
+          "profile" => profile,
+          "property_id" => property_id,
+          "date_ranges" => date_ranges,
+          "summary" => summary,
+          "findings" => findings.map(&:to_h)
+        }
+      end
+    end
+
+    # Internal report definitions used to calculate health.
+    module Definitions
+      module_function
+
+      def for(date_ranges)
+        [
+          Reports::Definition.new(
+            name: "health_totals",
+            kind: "standard",
+            dimensions: [],
+            metrics: %w[activeUsers sessions keyEvents],
+            date_ranges:,
+            limit: 2
+          ),
+          Reports::Definition.new(
+            name: "health_acquisition",
+            kind: "standard",
+            dimensions: ["sessionDefaultChannelGroup"],
+            metrics: ["sessions"],
+            date_ranges:,
+            limit: 250
+          ),
+          Reports::Definition.new(
+            name: "health_events",
+            kind: "standard",
+            dimensions: ["eventName"],
+            metrics: ["eventCount"],
+            date_ranges:,
+            limit: 10_000
+          )
+        ].freeze
+      end
+    end
+
+    # Evaluates bounded report results and configuration drift.
+    class Runner
+      def initialize(desired_state:, reports:, plan:, date_ranges:)
+        @desired_state = desired_state
+        @reports = reports
+        @plan = plan
+        @date_ranges = date_ranges
+        @settings = DEFAULTS.merge(desired_state.health || {})
+      end
+
+      def call
+        validate_inputs!
+        findings = []
+        totals = period_totals
+        findings.concat(traffic_findings(totals))
+        findings.concat(acquisition_findings(totals))
+        findings.concat(expected_event_findings)
+        findings.concat(metadata_findings)
+        findings.concat(drift_findings)
+        if findings.empty?
+          findings << Finding.new(
+            severity: "ok",
+            code: "checks_passed",
+            message: "No configured analytics health problem was detected",
+            actual: nil,
+            expected: nil
+          )
+        end
+
+        Result.new(
+          profile: @desired_state.profile,
+          property_id: @desired_state.property_id,
+          date_ranges: @date_ranges,
+          findings:,
+          summary: {
+            "current" => totals.fetch("current"),
+            "previous" => totals.fetch("previous")
+          }
+        )
+      end
+
+      private
+
+      def validate_inputs!
+        Health.validate_date_ranges!(@date_ranges)
+        expected_names = %w[health_totals health_acquisition health_events]
+        unless @reports.is_a?(Array) && @reports.map(&:name) == expected_names
+          raise RemoteError, "Health reports returned an unexpected shape"
+        end
+        raise RemoteError, "Health audit requires a plan" unless @plan.is_a?(Plan)
+      end
+
+      def period_totals
+        rows = report("health_totals").rows
+        indexed = rows.to_h { |row| [row.fetch("dateRange", "current"), row] }
+        zero = { "activeUsers" => "0", "sessions" => "0", "keyEvents" => "0" }
+        {
+          "current" => zero.merge(indexed.fetch("current", {})),
+          "previous" => zero.merge(indexed.fetch("previous", {}))
+        }
+      end
+
+      def traffic_findings(totals)
+        current = totals.fetch("current")
+        previous = totals.fetch("previous")
+        findings = []
+        sessions = number(current.fetch("sessions"))
+        if sessions < @settings.fetch("minimum_sessions")
+          findings << finding(
+            "warning", "low_traffic", "Traffic is below the configured minimum",
+            sessions, "at least #{@settings.fetch("minimum_sessions")} sessions"
+          )
+        end
+        findings.concat(drop_finding("traffic", sessions, number(previous.fetch("sessions")),
+                                     @settings.fetch("traffic_drop_percent")))
+        findings.concat(drop_finding("key_events", number(current.fetch("keyEvents")),
+                                     number(previous.fetch("keyEvents")),
+                                     @settings.fetch("key_event_drop_percent")))
+        findings
+      end
+
+      def drop_finding(name, current, previous, threshold)
+        return [] unless previous.positive?
+
+        drop = ((previous - current) / previous) * 100
+        return [] unless drop.positive?
+        return [] if drop < threshold
+
+        [finding(
+          "warning",
+          "#{name}_drop",
+          "#{name.tr("_", " ").capitalize} fell compared with the preceding period",
+          "#{rounded(drop)}% drop",
+          "less than #{rounded(threshold)}% drop"
+        )]
+      end
+
+      def acquisition_findings(totals)
+        total = number(totals.fetch("current").fetch("sessions"))
+        return [] unless total.positive?
+
+        current_rows = report("health_acquisition").rows.select do |row|
+          row.fetch("dateRange", "current") == "current"
+        end
+        {
+          "unassigned" => ["Unassigned", @settings.fetch("unassigned_percent")],
+          "not_set" => ["(not set)", @settings.fetch("not_set_percent")]
+        }.filter_map do |code, (label, threshold)|
+          matching_rows = current_rows.select { |row| row.fetch("sessionDefaultChannelGroup") == label }
+          sessions = matching_rows.sum { |row| number(row.fetch("sessions")) }
+          percent = (sessions / total) * 100
+          next unless percent.positive?
+          next if percent < threshold
+
+          finding(
+            "warning",
+            "high_#{code}",
+            "#{label} traffic is above the configured threshold",
+            "#{rounded(percent)}%",
+            "less than #{rounded(threshold)}%"
+          )
+        end
+      end
+
+      def expected_event_findings
+        observed_rows = report("health_events").rows.select do |row|
+          row.fetch("dateRange", "current") == "current" && number(row.fetch("eventCount")).positive?
+        end
+        observed = observed_rows.map { |row| row.fetch("eventName") }
+        @settings.fetch("expected_events").filter_map do |name|
+          next if observed.include?(name)
+
+          finding(
+            "warning", "missing_expected_event", "An expected event did not appear in the current period",
+            "not observed: #{name}", "event #{name}"
+          )
+        end
+      end
+
+      def metadata_findings
+        findings = @reports.flat_map { |result| report_metadata_findings(result) }
+        findings.uniq { |item| [item.code, item.actual] }
+      end
+
+      def report_metadata_findings(result)
+        findings = threshold_findings(result)
+        tokens = (result.metadata["property_quota"] || {})["tokens_per_day"]
+        findings.concat(quota_findings(tokens))
+      end
+
+      def threshold_findings(result)
+        findings = []
+        if result.metadata["subject_to_thresholding"]
+          findings << finding(
+            "warning", "thresholded_data", "Google reports that privacy thresholding affected this result",
+            result.name, "unthresholded result"
+          )
+        end
+        unless Array(result.metadata["sampling"]).empty?
+          findings << finding(
+            "warning", "sampled_data", "Google reports that sampling affected this result",
+            result.name, "unsampled result"
+          )
+        end
+        findings
+      end
+
+      def quota_findings(tokens)
+        return [] unless tokens
+
+        total = tokens.fetch("consumed") + tokens.fetch("remaining")
+        return [] unless total.positive? && tokens.fetch("remaining").fdiv(total) < 0.1
+
+        [finding(
+          "warning", "low_daily_quota", "Fewer than 10% of daily Data API tokens remain",
+          tokens.fetch("remaining"), "at least 10% remaining"
+        )]
+      end
+
+      def drift_findings
+        return [] unless @plan.drift?
+
+        [finding(
+          "warning",
+          "configuration_drift",
+          "Managed GA4 configuration differs from the saved configuration",
+          "#{@plan.changes.length} changes and #{@plan.findings.length} findings",
+          "no drift"
+        )]
+      end
+
+      def report(name)
+        @reports.find { |value| value.name == name } ||
+          raise(RemoteError, "Missing health report #{name}")
+      end
+
+      def number(value)
+        return BigDecimal(value) if value.is_a?(String) && value.match?(/\A-?\d+(?:\.\d+)?\z/)
+
+        raise RemoteError, "Health report contained a nonnumeric metric"
+      rescue ArgumentError
+        raise RemoteError, "Health report contained a nonnumeric metric"
+      end
+
+      def rounded(value)
+        format("%.1f", value)
+      end
+
+      def finding(severity, code, message, actual, expected)
+        Finding.new(severity:, code:, message:, actual: actual&.to_s, expected: expected&.to_s)
+      end
+    end
+  end
+end

data/lib/analytics_ops/mcp_server/custom_report_tool.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module AnalyticsOps
+  # Reopens the read-only MCP server to add custom reporting tools.
+  class MCPServer
+    # Bounded custom-report MCP tool with property-aware validation.
+    module CustomReportTool
+      FIELD_PATTERN = "^[a-z][a-zA-Z0-9_]*(?::[a-zA-Z][a-zA-Z0-9_]*)?$"
+
+      private
+
+      def define_custom_report_tool
+        owner = self
+        server.define_tool(
+          name: "analytics_run_custom_report",
+          title: "Run Custom Analytics Report",
+          description: "Run a bounded, property-validated custom GA4 report. This tool is read-only.",
+          input_schema: custom_report_schema,
+          output_schema: OBJECT_OUTPUT,
+          annotations: READ_ONLY_ANNOTATIONS
+        ) do |metrics:, profile: nil, dimensions: [], filters: [], limit: 100,
+                last_days: nil, start_date: nil, end_date: nil, compare: false, server_context: nil|
+          owner.__send__(:respond, server_context) do
+            ranges = owner.__send__(:date_ranges, last_days:, start_date:, end_date:, compare:) ||
+                     Reports::Catalog::STANDARD_DATE_RANGE
+            definition = owner.__send__(
+              :mcp_custom_definition,
+              dimensions:,
+              metrics:,
+              filters:,
+              date_ranges: ranges,
+              limit:
+            )
+            owner.__send__(:workspace, profile).report(definition)
+          end
+        end
+      end
+
+      def custom_report_schema
+        {
+          type: "object",
+          additionalProperties: false,
+          required: ["metrics"],
+          properties: PROFILE_INPUT.fetch(:properties).merge(PERIOD_PROPERTIES).merge(
+            dimensions: custom_field_array(9, minimum: 0),
+            metrics: custom_field_array(10, minimum: 1),
+            filters: custom_filter_schema,
+            limit: { type: "integer", minimum: 1, maximum: 1_000 }
+          )
+        }
+      end
+
+      def custom_field_array(maximum, minimum:)
+        {
+          type: "array",
+          minItems: minimum,
+          maxItems: maximum,
+          uniqueItems: true,
+          items: { type: "string", pattern: FIELD_PATTERN }
+        }
+      end
+
+      def custom_filter_schema
+        {
+          type: "array",
+          maxItems: 20,
+          items: {
+            type: "object",
+            additionalProperties: false,
+            required: %w[field value],
+            properties: {
+              field: { type: "string", pattern: FIELD_PATTERN },
+              value: { type: "string", minLength: 1, maxLength: 1_024 }
+            }
+          }
+        }
+      end
+
+      def mcp_custom_definition(dimensions:, metrics:, filters:, date_ranges:, limit:)
+        expressions = filters.map do |filter|
+          {
+            "field" => filter.fetch(:field, filter["field"]),
+            "match_type" => "exact",
+            "value" => filter.fetch(:value, filter["value"])
+          }
+        end
+        Reports::Definition.new(
+          name: "ai_custom_report",
+          kind: "standard",
+          dimensions:,
+          metrics:,
+          date_ranges:,
+          dimension_filter: expressions.length > 1 ? { "and" => expressions } : expressions.first,
+          limit:
+        )
+      end
+    end
+
+    include CustomReportTool
+  end
+end

data/lib/analytics_ops/mcp_server/discovery_tools.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module AnalyticsOps
+  # Reopens the read-only MCP server to add report discovery tools.
+  class MCPServer
+    # Report catalog, field metadata, and compatibility MCP tools.
+    module DiscoveryTools
+      private
+
+      def define_report_discovery_tools
+        define_report_list_tool
+        define_field_list_tool
+        define_compatibility_tool
+      end
+
+      def define_report_list_tool
+        owner = self
+        server.define_tool(
+          name: "analytics_list_reports",
+          title: "List Analytics Reports",
+          description: "List safe built-in and locally configured report recipes.",
+          input_schema: PROFILE_INPUT,
+          output_schema: OBJECT_OUTPUT,
+          annotations: READ_ONLY_ANNOTATIONS
+        ) do |profile: nil, server_context: nil|
+          owner.__send__(:respond, server_context) { owner.__send__(:workspace, profile).report_recipes }
+        end
+      end
+
+      def define_field_list_tool
+        owner = self
+        server.define_tool(
+          name: "analytics_list_report_fields",
+          title: "Find Analytics Report Fields",
+          description: "Search property-aware GA4 dimensions and metrics before constructing a report.",
+          input_schema: {
+            type: "object",
+            additionalProperties: false,
+            properties: PROFILE_INPUT.fetch(:properties).merge(
+              query: { type: "string", minLength: 1, maxLength: 128 },
+              kind: { type: "string", enum: %w[dimension metric] }
+            )
+          },
+          output_schema: OBJECT_OUTPUT,
+          annotations: READ_ONLY_ANNOTATIONS
+        ) do |profile: nil, query: nil, kind: nil, server_context: nil|
+          owner.__send__(:respond, server_context) do
+            owner.__send__(:workspace, profile).report_metadata(query:, kind:)
+          end
+        end
+      end
+
+      def define_compatibility_tool
+        owner = self
+        server.define_tool(
+          name: "analytics_check_report",
+          title: "Check Analytics Report Compatibility",
+          description: "Check whether a built-in or configured report's fields work together for this property.",
+          input_schema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["report"],
+            properties: PROFILE_INPUT.fetch(:properties).merge(
+              report: { type: "string", pattern: "^[a-z][a-z0-9_-]{0,63}$" }
+            )
+          },
+          output_schema: OBJECT_OUTPUT,
+          annotations: READ_ONLY_ANNOTATIONS
+        ) do |report:, profile: nil, server_context: nil|
+          owner.__send__(:respond, server_context) do
+            owner.__send__(:workspace, profile).report_compatibility(report)
+          end
+        end
+      end
+    end
+
+    include DiscoveryTools
+  end
+end

data/lib/analytics_ops/mcp_server/experimental_tools.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module AnalyticsOps
+  # Reopens the read-only MCP server to add experimental inspection tools.
+  class MCPServer
+    # Experimental read-only BigQuery and governance MCP tools.
+    module ExperimentalTools
+      private
+
+      def define_experimental_read_tools
+        define_profile_tool(
+          "analytics_governance",
+          "Audit Analytics Governance",
+          "Read broader GA4 governance settings. This is experimental and cannot change them.",
+          OBJECT_OUTPUT
+        ) { |profile| workspace(profile).governance }
+        define_profile_tool(
+          "analytics_access_report",
+          "Read Aggregate Analytics API Usage",
+          "Read aggregate Data API quota usage by hour without user-email or IP fields. This is experimental.",
+          OBJECT_OUTPUT
+        ) { |profile| workspace(profile).access_report }
+        define_bigquery_report_tool
+        define_funnel_tool
+      end
+
+      def define_bigquery_report_tool
+        owner = self
+        server.define_tool(
+          name: "analytics_run_bigquery_report",
+          title: "Run Cost-Capped BigQuery Report",
+          description: "Run one fixed, read-only BigQuery recipe. No arbitrary SQL is accepted.",
+          input_schema: experimental_report_schema(
+            "report",
+            { type: "string", enum: BigQuery::RECIPE_NAMES },
+            limit: { type: "integer", minimum: 1, maximum: 1_000 }
+          ),
+          output_schema: OBJECT_OUTPUT,
+          annotations: READ_ONLY_ANNOTATIONS
+        ) do |report:, profile: nil, limit: 100, last_days: nil, start_date: nil, end_date: nil,
+                compare: false, server_context: nil|
+          owner.__send__(:respond, server_context) do
+            raise InvalidRequestError, "BigQuery reports do not support comparison ranges" if compare
+
+            ranges = owner.__send__(:date_ranges, last_days:, start_date:, end_date:, compare:)
+            owner.__send__(:workspace, profile).raw_report(report, date_ranges: ranges, limit:)
+          end
+        end
+      end
+
+      def define_funnel_tool
+        owner = self
+        server.define_tool(
+          name: "analytics_run_funnel",
+          title: "Run Aggregate Analytics Funnel",
+          description: "Run one configured aggregate funnel through the cost-capped BigQuery connection.",
+          input_schema: experimental_report_schema(
+            "funnel",
+            { type: "string", pattern: "^[A-Za-z][A-Za-z0-9_]{0,63}$" }
+          ),
+          output_schema: OBJECT_OUTPUT,
+          annotations: READ_ONLY_ANNOTATIONS
+        ) do |funnel:, profile: nil, last_days: nil, start_date: nil, end_date: nil,
+                compare: false, server_context: nil|
+          owner.__send__(:respond, server_context) do
+            raise InvalidRequestError, "Funnel reports do not support comparison ranges" if compare
+
+            ranges = owner.__send__(:date_ranges, last_days:, start_date:, end_date:, compare:)
+            owner.__send__(:workspace, profile).funnel(funnel, date_ranges: ranges)
+          end
+        end
+      end
+
+      def experimental_report_schema(name, definition, extra = {})
+        {
+          type: "object",
+          additionalProperties: false,
+          required: [name],
+          properties: PROFILE_INPUT.fetch(:properties)
+                                   .merge(PERIOD_PROPERTIES)
+                                   .merge(name.to_sym => definition)
+                                   .merge(extra)
+        }
+      end
+    end
+
+    include ExperimentalTools
+  end
+end

data/lib/analytics_ops/mcp_server/health_tools.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module AnalyticsOps
+  # Reopens the read-only MCP server to add health tools.
+  class MCPServer
+    # Single-profile and portfolio health/report MCP tools.
+    module HealthTools
+      private
+
+      def define_health_tools
+        define_profile_health_tool
+        define_portfolio_report_tool
+        define_portfolio_health_tool
+      end
+
+      def define_profile_health_tool
+        owner = self
+        server.define_tool(
+          name: "analytics_health",
+          title: "Check Analytics Health",
+          description: "Check traffic, expected events, acquisition quality, quota, and configuration drift.",
+          input_schema: health_period_schema(profile: true),
+          output_schema: OBJECT_OUTPUT,
+          annotations: READ_ONLY_ANNOTATIONS
+        ) do |profile: nil, last_days: nil, start_date: nil, end_date: nil, server_context: nil|
+          owner.__send__(:respond, server_context) do
+            ranges = owner.__send__(:date_ranges, last_days:, start_date:, end_date:, compare: true)
+            target = owner.__send__(:workspace, profile)
+            ranges ? target.health(date_ranges: ranges) : target.health
+          end
+        end
+      end
+
+      def define_portfolio_report_tool
+        owner = self
+        server.define_tool(
+          name: "analytics_portfolio_report",
+          title: "Run Report Across Analytics Properties",
+          description: "Run one safe report across every configured profile with isolated per-property failures.",
+          input_schema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["report"],
+            properties: PERIOD_PROPERTIES.merge(
+              report: { type: "string", pattern: "^[a-z][a-z0-9_-]{0,63}$" }
+            )
+          },
+          output_schema: OBJECT_OUTPUT,
+          annotations: READ_ONLY_ANNOTATIONS
+        ) do |report:, last_days: nil, start_date: nil, end_date: nil, compare: false, server_context: nil|
+          owner.__send__(:respond, server_context) do
+            ranges = owner.__send__(:date_ranges, last_days:, start_date:, end_date:, compare:)
+            target = owner.__send__(:portfolio)
+            ranges ? target.report(report, date_ranges: ranges) : target.report(report)
+          end
+        end
+      end
+
+      def define_portfolio_health_tool
+        owner = self
+        server.define_tool(
+          name: "analytics_portfolio_health",
+          title: "Check Every Analytics Property",
+          description: "Run deterministic health checks across every configured profile.",
+          input_schema: health_period_schema(profile: false),
+          output_schema: OBJECT_OUTPUT,
+          annotations: READ_ONLY_ANNOTATIONS
+        ) do |last_days: nil, start_date: nil, end_date: nil, server_context: nil|
+          owner.__send__(:respond, server_context) do
+            ranges = owner.__send__(:date_ranges, last_days:, start_date:, end_date:, compare: true)
+            target = owner.__send__(:portfolio)
+            ranges ? target.health(date_ranges: ranges) : target.health
+          end
+        end
+      end
+    end
+
+    include HealthTools
+  end
+end