analytics_ops 0.1.0

data/lib/analytics_ops/reports/result.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module AnalyticsOps
+  module Reports
+    # Immutable normalized Data API response.
+    class Result
+      attr_reader :name, :kind, :dimension_headers, :metric_headers, :rows, :row_count, :metadata
+
+      def initialize(name:, kind:, dimension_headers:, metric_headers:, rows:, row_count:, metadata:)
+        @name = string(name, "name")
+        @kind = kind_value(kind)
+        @dimension_headers = normalize_headers(dimension_headers, "dimension_headers")
+        @metric_headers = normalize_headers(metric_headers, "metric_headers")
+        validate_header_uniqueness!
+        @rows = normalized_rows(rows)
+        @row_count = count(row_count)
+        @metadata = hash(metadata, "metadata")
+        freeze
+      end
+
+      def headers
+        dimension_headers + metric_headers
+      end
+
+      def to_h
+        {
+          "name" => name,
+          "kind" => kind,
+          "dimension_headers" => dimension_headers,
+          "metric_headers" => metric_headers,
+          "rows" => rows,
+          "row_count" => row_count,
+          "metadata" => metadata
+        }
+      end
+
+      private
+
+      def string(value, label)
+        return value.dup.freeze if value.is_a?(String) && !value.empty?
+
+        raise RemoteError, "Report result #{label} is invalid"
+      end
+
+      def kind_value(value)
+        return value.dup.freeze if Definition::KINDS.include?(value)
+
+        raise RemoteError, "Report result kind is invalid"
+      end
+
+      def normalize_headers(values, label)
+        unless values.is_a?(Array) && values.all? { |value| value.is_a?(String) && !value.empty? }
+          raise RemoteError, "Report result #{label} is invalid"
+        end
+
+        Canonical.immutable(values)
+      end
+
+      def validate_header_uniqueness!
+        raise RemoteError, "Report result headers are not unique" unless headers.uniq.length == headers.length
+      end
+
+      def normalized_rows(values)
+        raise RemoteError, "Report result rows must be an array" unless values.is_a?(Array)
+
+        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
+
+          value
+        end
+        Canonical.immutable(normalized)
+      end
+
+      def count(value)
+        return value if value.is_a?(Integer) && value >= rows.length
+
+        raise RemoteError, "Report result row_count is invalid"
+      end
+
+      def hash(value, label)
+        unless value.is_a?(Hash) && value.keys.all?(String)
+          raise RemoteError, "Report result #{label} must be an object with string keys"
+        end
+
+        Canonical.immutable(value)
+      end
+    end
+  end
+end

data/lib/analytics_ops/reports.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Reporting public namespace.
+
+require_relative "reports/definition"
+require_relative "reports/catalog"
+require_relative "reports/result"
+
+module AnalyticsOps
+  # Immutable Data API definitions, recipes, and normalized results.
+  module Reports
+  end
+end

data/lib/analytics_ops/resources.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+# Gem-owned values returned at public API boundaries.
+
+module AnalyticsOps
+  module Resources
+    # Immutable base class for gem-owned values at the Google client boundary.
+    class Value
+      class << self
+        attr_reader :field_names
+
+        def fields(*names)
+          @field_names = names.freeze
+          attr_reader(*names)
+        end
+      end
+
+      def initialize(**values)
+        unknown = values.keys - self.class.field_names
+        missing = self.class.field_names - values.keys
+        raise ArgumentError, "Unknown fields: #{unknown.join(", ")}" unless unknown.empty?
+        raise ArgumentError, "Missing fields: #{missing.join(", ")}" unless missing.empty?
+
+        values.each do |name, value|
+          instance_variable_set("@#{name}", Canonical.immutable(value))
+        end
+        freeze
+      end
+
+      def to_h
+        self.class.field_names.to_h { |name| [name.to_s, public_send(name)] }
+      end
+
+      def ==(other)
+        other.instance_of?(self.class) && other.to_h == to_h
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, to_h].hash
+      end
+    end
+
+    # Accessible Analytics account summary.
+    class Account < Value
+      fields :id, :name, :display_name, :properties
+    end
+
+    # Normalized GA4 property.
+    class Property < Value
+      fields :id, :name, :display_name, :parent, :property_type, :can_edit
+    end
+
+    # Normalized web or application data stream.
+    class DataStream < Value
+      fields :id, :name, :display_name, :type, :default_uri, :measurement_id
+    end
+
+    # Property retention settings.
+    class Retention < Value
+      fields :name, :event_data, :user_data, :reset_on_new_activity
+    end
+
+    # Registered key event.
+    class KeyEvent < Value
+      fields :name, :event_name, :counting_method
+    end
+
+    # Registered custom dimension.
+    class CustomDimension < Value
+      fields :name, :parameter_name, :display_name, :description, :scope, :disallow_ads_personalization
+    end
+
+    # Registered custom metric.
+    class CustomMetric < Value
+      fields :name, :parameter_name, :display_name, :description, :scope, :measurement_unit
+    end
+  end
+end

data/lib/analytics_ops/snapshot.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# Normalized remote state.
+
+module AnalyticsOps
+  # Normalized remote state. No generated Google objects escape into this value.
+  class Snapshot
+    attr_reader :property, :streams, :retention, :key_events, :custom_dimensions, :custom_metrics
+
+    def initialize(property:, streams:, retention:, key_events:, custom_dimensions:, custom_metrics:)
+      @property = property
+      @streams = sort(streams, &:id)
+      @retention = retention
+      @key_events = sort(key_events, &:event_name)
+      @custom_dimensions = sort(custom_dimensions) { |dimension| [dimension.scope, dimension.parameter_name] }
+      @custom_metrics = sort(custom_metrics, &:parameter_name)
+      freeze
+    end
+
+    def property_id
+      property.id
+    end
+
+    def to_h
+      {
+        "property" => property.to_h,
+        "streams" => streams.map(&:to_h),
+        "retention" => retention&.to_h,
+        "key_events" => key_events.map(&:to_h),
+        "custom_dimensions" => custom_dimensions.map(&:to_h),
+        "custom_metrics" => custom_metrics.map(&:to_h)
+      }
+    end
+
+    def fingerprint
+      Canonical.fingerprint(to_h)
+    end
+
+    private
+
+    def sort(values, &)
+      Canonical.deep_freeze(values.sort_by(&))
+    end
+  end
+end

data/lib/analytics_ops/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AnalyticsOps
+  VERSION = "0.1.0"
+end

data/lib/analytics_ops/workspace.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+# Primary plain-Ruby API.
+
+require "time"
+
+module AnalyticsOps
+  # Primary Ruby API. Loading a workspace validates local data but performs no network calls.
+  class Workspace
+    # Immutable convergence result returned by verify.
+    class Verification
+      attr_reader :converged, :plan
+
+      def initialize(plan:)
+        @plan = plan
+        @converged = !plan.drift?
+        freeze
+      end
+
+      def to_h
+        { "converged" => converged, "plan" => plan.to_h }
+      end
+    end
+
+    # Immutable health-check collection returned by doctor.
+    class DoctorResult
+      attr_reader :checks
+
+      def initialize(checks:)
+        @checks = Canonical.deep_freeze(checks)
+        freeze
+      end
+
+      def success?
+        checks.none? { |check| check.fetch("status") == "error" }
+      end
+
+      def to_h
+        { "success" => success?, "checks" => checks }
+      end
+    end
+
+    attr_reader :desired_state
+
+    def self.load(path, profile:, environment: ENV, admin: nil, data: nil, credentials: nil,
+                  transport: :grpc, timeout: nil, logger: nil)
+      document = Configuration.load(path, environment:)
+      new(desired_state: document.profile(profile), admin:, data:, credentials:, transport:, timeout:, logger:)
+    end
+
+    def initialize(desired_state:, admin: nil, data: nil, credentials: nil, transport: :grpc, timeout: nil, logger: nil)
+      @desired_state = desired_state
+      @admin = admin
+      @data = data
+      @credentials = credentials
+      @transport = transport
+      @timeout = timeout
+      @logger = logger
+    end
+
+    def discover
+      admin.discover
+    end
+
+    def snapshot
+      admin.snapshot(desired_state.property_id)
+    end
+
+    def audit
+      plan
+    end
+
+    def plan
+      Planner.new(desired_state:, snapshot:).call
+    end
+
+    def apply(plan_or_path, confirm: false)
+      saved_plan = plan_or_path.is_a?(Plan) ? plan_or_path : Plan.load(plan_or_path)
+      validate_plan_target!(saved_plan)
+      Applier.new(admin:).call(saved_plan, confirm:)
+    end
+
+    def verify
+      Verification.new(plan:)
+    end
+
+    def report(name_or_definition)
+      definition = report_definition(name_or_definition, kind: "standard")
+      data.run(desired_state.property_id, definition)
+    end
+
+    def realtime(name_or_definition = "realtime_events")
+      definition = report_definition(name_or_definition, kind: "realtime")
+      data.run(desired_state.property_id, definition)
+    end
+
+    def doctor
+      remote = snapshot
+      checks = [
+        { "name" => "configuration", "status" => "ok", "detail" => "Profile #{desired_state.profile} is valid" },
+        { "name" => "credentials", "status" => "ok", "detail" => "Google accepted discovered or injected credentials" },
+        { "name" => "admin_api", "status" => "ok", "detail" => "Admin API read succeeded" },
+        { "name" => "property_access", "status" => "ok", "detail" => "Read properties/#{remote.property_id}" }
+      ]
+      checks.concat(compatibility_checks)
+      checks << clock_check
+      checks << edit_capability_check
+      data.run(desired_state.property_id, doctor_report_definition)
+      checks << { "name" => "data_api", "status" => "ok", "detail" => "Data API read succeeded" }
+      checks << {
+        "name" => "oauth_scopes",
+        "status" => "unknown",
+        "detail" => "Installed Google clients do not expose a reliable token-scope inspection contract"
+      }
+      admin.capabilities.each do |name, available|
+        checks << {
+          "name" => name,
+          "status" => available ? "ok" : "unsupported",
+          "detail" => available ? "Installed client exposes this capability" : "Installed client lacks this capability"
+        }
+      end
+      DoctorResult.new(checks:)
+    end
+
+    private
+
+    def admin
+      @admin ||= Clients::Admin.new(
+        credentials: @credentials,
+        transport: @transport,
+        timeout: @timeout,
+        logger: @logger
+      )
+    end
+
+    def data
+      @data ||= Clients::Data.new(
+        credentials: @credentials,
+        transport: @transport,
+        timeout: @timeout,
+        logger: @logger
+      )
+    end
+
+    def compatibility_checks
+      [admin.compatibility, data.compatibility].map do |details|
+        {
+          "name" => details.fetch("package"),
+          "status" => details.fetch("supported") ? "ok" : "unsupported",
+          "detail" => "Installed #{details.fetch("version")}; supported #{details.fetch("requirement")}; " \
+                      "transport #{details.fetch("transport")}"
+        }
+      end
+    end
+
+    def clock_check
+      now = Time.now.utc
+      plausible = now.year.between?(2024, 2100)
+      {
+        "name" => "local_clock",
+        "status" => plausible ? "ok" : "error",
+        "detail" => plausible ? "Local UTC clock is plausible: #{now.iso8601}" : "Local UTC clock is implausible"
+      }
+    end
+
+    def edit_capability_check
+      access = admin.property_access(desired_state.property_id)
+      case access.can_edit
+      when true
+        { "name" => "edit_capability", "status" => "ok", "detail" => "Account summary reports edit access" }
+      when false
+        { "name" => "edit_capability", "status" => "warning", "detail" => "Account summary reports read-only access" }
+      else
+        { "name" => "edit_capability", "status" => "unknown", "detail" => "Google did not report edit capability" }
+      end
+    end
+
+    def doctor_report_definition
+      Reports::Definition.new(
+        name: "doctor_connectivity",
+        kind: "standard",
+        dimensions: ["eventName"],
+        metrics: ["eventCount"],
+        date_ranges: [{ "start_date" => "yesterday", "end_date" => "yesterday" }],
+        limit: 1
+      )
+    end
+
+    def report_definition(name_or_definition, kind:)
+      definition = if name_or_definition.is_a?(Reports::Definition)
+                     name_or_definition
+                   else
+                     Reports::Catalog.fetch(name_or_definition, kind:)
+                   end
+      unless definition.kind == kind
+        raise InvalidRequestError, "Report #{definition.name} is #{definition.kind}, not #{kind}"
+      end
+
+      definition
+    end
+
+    def validate_plan_target!(saved_plan)
+      unless saved_plan.profile == desired_state.profile
+        raise InvalidPlanError,
+              "Plan profile #{saved_plan.profile.inspect} does not match #{desired_state.profile.inspect}"
+      end
+      return if saved_plan.property_id == desired_state.property_id
+
+      raise InvalidPlanError, "Plan property #{saved_plan.property_id} does not match configured property"
+    end
+  end
+end

data/lib/analytics_ops.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "analytics_ops/version"
+require_relative "analytics_ops/errors"
+require_relative "analytics_ops/redaction"
+require_relative "analytics_ops/canonical"
+require_relative "analytics_ops/resources"
+require_relative "analytics_ops/desired_state"
+require_relative "analytics_ops/configuration"
+require_relative "analytics_ops/snapshot"
+require_relative "analytics_ops/plan"
+require_relative "analytics_ops/planner"
+require_relative "analytics_ops/clients/admin"
+require_relative "analytics_ops/reports"
+require_relative "analytics_ops/clients/data"
+require_relative "analytics_ops/applier"
+require_relative "analytics_ops/workspace"
+
+# Safe Google Analytics 4 configuration and reporting operations.
+module AnalyticsOps
+end

data/lib/generators/analytics_ops/install_generator.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module AnalyticsOps
+  module Generators
+    # Installs only configuration and a project-local CLI launcher.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Create config/analytics_ops.yml and bin/analytics-ops"
+
+      def copy_configuration
+        template "analytics_ops.yml", "config/analytics_ops.yml"
+      end
+
+      def copy_executable
+        copy_file "analytics-ops", "bin/analytics-ops"
+        File.chmod(0o755, File.join(destination_root, "bin/analytics-ops"))
+      end
+    end
+  end
+end

data/lib/generators/analytics_ops/templates/analytics-ops

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+require "bundler/setup"
+require "analytics_ops/cli"
+
+exit AnalyticsOps::CLI.start(ARGV)

data/lib/generators/analytics_ops/templates/analytics_ops.yml

@@ -0,0 +1,23 @@
+# Analytics Ops contains desired GA4 state only. Never place credentials here.
+version: 1
+
+profiles:
+  development:
+    # GA4 property ID (numeric), not an account ID, stream ID, or measurement ID.
+    property_id: "${GA4_PROPERTY_ID}"
+
+    streams:
+      web:
+        # Numeric stream ID from Admin > Data streams, not the G- measurement ID.
+        stream_id: "${GA4_STREAM_ID}"
+        default_uri: "https://example.test"
+
+    retention:
+      event_data: 14_months
+      user_data: 14_months
+      reset_on_new_activity: false
+
+    key_events: []
+    custom_dimensions: []
+    custom_metrics: []
+    manual_requirements: []