analytics_ops 0.1.0 → 0.2.0

data/lib/analytics_ops/setup.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module AnalyticsOps
+  # Interactive or automated property selection after service-account loading.
+  class Setup
+    PROPERTY_ID = /\A\d{1,50}\z/
+    PROFILE = /\A[A-Za-z][A-Za-z0-9_]{0,63}\z/
+
+    # Immutable setup outcome returned to the CLI and Ruby callers.
+    class Result
+      attr_reader :config_path, :profile, :property
+
+      def initialize(config_path:, profile:, property:, created:)
+        unless property.is_a?(Resources::Property)
+          raise ArgumentError, "property must be an AnalyticsOps::Resources::Property"
+        end
+        raise ArgumentError, "created must be true or false" unless [true, false].include?(created)
+
+        @config_path = config_path.to_s.dup.freeze
+        @profile = profile.to_s.dup.freeze
+        @property = property
+        @created = created
+        freeze
+      end
+
+      def created?
+        @created
+      end
+
+      def status
+        created? ? "configured" : "already_configured"
+      end
+
+      def to_h
+        {
+          "status" => status,
+          "config" => config_path,
+          "profile" => profile,
+          "property" => property.to_h
+        }
+      end
+    end
+
+    def initialize(connection:, config:, profile:, property_id: nil, noninteractive: false,
+                   input: $stdin, out: $stdout)
+      validate_options!(
+        config:,
+        profile:,
+        property_id:,
+        noninteractive:
+      )
+      @connection = connection
+      @config = config
+      @profile = profile.to_s
+      @property_id = property_id
+      @noninteractive = noninteractive
+      @input = input
+      @out = out
+    end
+
+    def call
+      selection = select_property(google_call { @connection.properties })
+      verification = google_call { @connection.verify(selection.fetch("id")) }
+      write = Configuration::Writer.new.write_minimal(
+        @config,
+        profile: @profile,
+        property_id: verification.property.id
+      )
+      Result.new(
+        config_path: write.path,
+        profile: @profile,
+        property: verification.property,
+        created: write.created?
+      )
+    end
+
+    private
+
+    def validate_options!(config:, profile:, property_id:, noninteractive:)
+      validate_config_path!(config)
+      validate_profile!(profile)
+      validate_property_id!(property_id)
+      validate_boolean_option!(noninteractive)
+      raise ConfigurationError, "Non-interactive setup requires a property ID" if noninteractive && !property_id
+    end
+
+    def validate_config_path!(config)
+      valid = config.is_a?(String) && !config.empty? && !config.match?(/[\u0000-\u001f\u007f]/)
+      return if valid
+
+      raise ConfigurationError, "Setup configuration path is invalid"
+    end
+
+    def validate_profile!(profile)
+      raise ConfigurationError, "Setup profile is invalid" unless PROFILE.match?(profile.to_s)
+    end
+
+    def validate_property_id!(property_id)
+      return if property_id.nil? || (property_id.is_a?(String) && PROPERTY_ID.match?(property_id))
+
+      raise ConfigurationError, "Setup property must be a numeric GA4 property ID"
+    end
+
+    def validate_boolean_option!(noninteractive)
+      return if [true, false].include?(noninteractive)
+
+      raise ConfigurationError, "Setup boolean options must be true or false"
+    end
+
+    def google_call
+      yield
+    rescue AuthorizationError, InvalidRequestError, RemoteError => error
+      raise_disabled_api! if api_disabled?(error)
+
+      raise
+    end
+
+    def api_disabled?(error)
+      error.message.match?(/SERVICE_DISABLED|API.*(?:disabled|not been used)|serviceusage/i)
+    end
+
+    def raise_disabled_api!
+      raise RemoteError,
+            "Google Analytics APIs appear disabled. Enable Google Analytics Admin API and " \
+            "Google Analytics Data API in the Google Cloud project that owns the service account."
+    end
+
+    def select_property(accounts)
+      choices = property_choices(accounts)
+      raise AuthorizationError, "No accessible Google Analytics properties found" if choices.empty?
+
+      return explicit_property(choices) if @property_id
+      return choices.first if choices.one?
+
+      prompt_for_property(choices)
+    end
+
+    def explicit_property(choices)
+      choices.find { |choice| choice.fetch("id") == @property_id } ||
+        raise(AuthorizationError, "Property #{@property_id} is not accessible")
+    end
+
+    def prompt_for_property(choices)
+      @out.puts "Choose a Google Analytics property:"
+      choices.each.with_index(1) do |choice, index|
+        @out.puts "  #{index}. #{Redaction.message(choice.fetch("display_name"))} — " \
+                  "#{Redaction.message(choice.fetch("account_display_name"))} " \
+                  "(property #{Redaction.message(choice.fetch("id"))})"
+      end
+      @out.print "Property number: "
+      @out.flush
+      index = Integer(@input.gets&.strip, exception: false)
+      unless index&.between?(1, choices.length)
+        raise ConfigurationError, "A property number from 1 to #{choices.length} is required"
+      end
+
+      choices.fetch(index - 1)
+    end
+
+    def property_choices(accounts)
+      choices = accounts.flat_map do |account|
+        account.properties.map do |property|
+          property.merge("account_id" => account.id, "account_display_name" => account.display_name)
+        end
+      end
+      choices.sort_by do |property|
+        [property.fetch("account_display_name"), property.fetch("display_name"), property.fetch("id")]
+      end
+    end
+  end
+end

data/lib/analytics_ops/snapshot.rb

@@ -8,12 +8,23 @@ module AnalyticsOps
     attr_reader :property, :streams, :retention, :key_events, :custom_dimensions, :custom_metrics
 
     def initialize(property:, streams:, retention:, key_events:, custom_dimensions:, custom_metrics:)
+      unless property.is_a?(Resources::Property)
+        raise ArgumentError, "property must be an AnalyticsOps::Resources::Property"
+      end
+      unless retention.nil? || retention.is_a?(Resources::Retention)
+        raise ArgumentError, "retention must be an AnalyticsOps::Resources::Retention or nil"
+      end
+
       @property = property
-      @streams = sort(streams, &:id)
+      @streams = sorted_resources(streams, Resources::DataStream, "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)
+      @key_events = sorted_resources(key_events, Resources::KeyEvent, "key_events", &:event_name)
+      @custom_dimensions = sorted_resources(
+        custom_dimensions, Resources::CustomDimension, "custom_dimensions"
+      ) do |item|
+        [item.scope, item.parameter_name]
+      end
+      @custom_metrics = sorted_resources(custom_metrics, Resources::CustomMetric, "custom_metrics", &:parameter_name)
       freeze
     end
 
@@ -38,7 +49,11 @@ module AnalyticsOps
 
     private
 
-    def sort(values, &)
+    def sorted_resources(values, type, label, &)
+      unless values.is_a?(Array) && values.all?(type)
+        raise ArgumentError, "#{label} must contain only #{type.name} values"
+      end
+
       Canonical.deep_freeze(values.sort_by(&))
     end
   end

data/lib/analytics_ops/version.rb

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

data/lib/analytics_ops/workspace.rb

@@ -27,7 +27,7 @@ module AnalyticsOps
       attr_reader :checks
 
       def initialize(checks:)
-        @checks = Canonical.deep_freeze(checks)
+        @checks = Canonical.immutable(checks)
         freeze
       end
 
@@ -42,17 +42,23 @@ module AnalyticsOps
 
     attr_reader :desired_state
 
-    def self.load(path, profile:, environment: ENV, admin: nil, data: nil, credentials: nil,
+    def self.load(path, profile:, environment: ENV, admin: nil, data: nil, service_account: nil,
                   transport: :grpc, timeout: nil, logger: nil)
       document = Configuration.load(path, environment:)
-      new(desired_state: document.profile(profile), admin:, data:, credentials:, transport:, timeout:, logger:)
+      new(desired_state: document.profile(profile), admin:, data:, service_account:, transport:, timeout:, logger:)
     end
 
-    def initialize(desired_state:, admin: nil, data: nil, credentials: nil, transport: :grpc, timeout: nil, logger: nil)
+    def initialize(desired_state:, admin: nil, data: nil, service_account: nil,
+                   transport: :grpc, timeout: nil, logger: nil)
+      unless service_account.nil? || service_account.is_a?(ServiceAccount)
+        raise ConfigurationError, "service_account must be an AnalyticsOps::ServiceAccount"
+      end
+
       @desired_state = desired_state
       @admin = admin
+      @injected_admin = admin
       @data = data
-      @credentials = credentials
+      @service_account = service_account
       @transport = transport
       @timeout = timeout
       @logger = logger
@@ -77,7 +83,7 @@ module AnalyticsOps
     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:)
+      Applier.new(admin: edit_admin).call(saved_plan, confirm:)
     end
 
     def verify
@@ -94,11 +100,17 @@ module AnalyticsOps
       data.run(desired_state.property_id, definition)
     end
 
+    def overview
+      reports = data.batch(desired_state.property_id, Reports::Catalog.overview)
+      Reports::OverviewResult.new(property_id: desired_state.property_id, reports:)
+    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" => "credentials", "status" => "ok",
+          "detail" => "Google accepted the configured service-account credentials" },
         { "name" => "admin_api", "status" => "ok", "detail" => "Admin API read succeeded" },
         { "name" => "property_access", "status" => "ok", "detail" => "Read properties/#{remote.property_id}" }
       ]
@@ -108,9 +120,9 @@ module AnalyticsOps
       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"
+        "name" => "credential_scope",
+        "status" => "ok",
+        "detail" => "This read-only command uses the Analytics read-only scope"
       }
       admin.capabilities.each do |name, available|
         checks << {
@@ -126,7 +138,8 @@ module AnalyticsOps
 
     def admin
       @admin ||= Clients::Admin.new(
-        credentials: @credentials,
+        service_account:,
+        access: :read,
         transport: @transport,
         timeout: @timeout,
         logger: @logger
@@ -135,13 +148,29 @@ module AnalyticsOps
 
     def data
       @data ||= Clients::Data.new(
-        credentials: @credentials,
+        service_account:,
         transport: @transport,
         timeout: @timeout,
         logger: @logger
       )
     end
 
+    def edit_admin
+      return @injected_admin if @injected_admin
+
+      @edit_admin ||= Clients::Admin.new(
+        service_account:,
+        access: :edit,
+        transport: @transport,
+        timeout: @timeout,
+        logger: @logger
+      )
+    end
+
+    def service_account
+      @service_account ||= ServiceAccount.load
+    end
+
     def compatibility_checks
       [admin.compatibility, data.compatibility].map do |details|
         {

data/lib/analytics_ops.rb

@@ -3,6 +3,7 @@
 require_relative "analytics_ops/version"
 require_relative "analytics_ops/errors"
 require_relative "analytics_ops/redaction"
+require_relative "analytics_ops/service_account"
 require_relative "analytics_ops/canonical"
 require_relative "analytics_ops/resources"
 require_relative "analytics_ops/desired_state"
@@ -10,9 +11,12 @@ 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/error_translation"
 require_relative "analytics_ops/clients/admin"
 require_relative "analytics_ops/reports"
 require_relative "analytics_ops/clients/data"
+require_relative "analytics_ops/connection"
+require_relative "analytics_ops/setup"
 require_relative "analytics_ops/applier"
 require_relative "analytics_ops/workspace"
 

data/lib/generators/analytics_ops/install_generator.rb

@@ -11,6 +11,8 @@ module AnalyticsOps
       desc "Create config/analytics_ops.yml and bin/analytics-ops"
 
       def copy_configuration
+        return if File.exist?(File.join(destination_root, "config/analytics_ops.yml"))
+
         template "analytics_ops.yml", "config/analytics_ops.yml"
       end
 

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

@@ -6,18 +6,5 @@ profiles:
     # 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: []
+    # Add managed settings only after reviewing the Analytics Ops configuration guide.
+    # This generated starting point produces no mutation plan by itself.

data/sig/analytics_ops.rbs

@@ -54,6 +54,30 @@ module AnalyticsOps
     def initialize: (String message, result: Applier::Result) -> void
   end
 
+  class ServiceAccount
+    MAX_KEY_BYTES: Integer
+    READ_SCOPE: String
+    EDIT_SCOPE: String
+    ACCESS_SCOPES: Hash[Symbol, Array[String]]
+
+    attr_reader path: String
+
+    def self.load: (?path: String?, ?store: Store) -> ServiceAccount
+    def initialize: (String path) -> void
+
+    class Store
+      VERSION: Integer
+      MAX_BYTES: Integer
+
+      attr_reader path: String
+
+      def self.default_path: () -> String
+      def initialize: (?path: String?) -> void
+      def read: () -> String
+      def write: (String service_account_path) -> String
+    end
+  end
+
   module Resources
     class Value
       def to_h: () -> record
@@ -116,6 +140,7 @@ module AnalyticsOps
       attr_reader description: String
       attr_reader scope: String
       attr_reader measurement_unit: String
+      attr_reader restricted_metric_types: Array[String]
     end
   end
 
@@ -131,6 +156,18 @@ module AnalyticsOps
       def initialize: (version: Integer, profiles: Hash[String, DesiredState]) -> void
       def profile: (String | Symbol name) -> DesiredState
     end
+
+    class Writer
+      class Result
+        attr_reader path: String
+
+        def initialize: (path: String, created: bool) -> void
+        def created?: () -> bool
+        def to_h: () -> record
+      end
+
+      def write_minimal: (String path, profile: String | Symbol, property_id: String) -> Result
+    end
   end
 
   class DesiredState
@@ -277,6 +314,8 @@ module AnalyticsOps
     module Catalog
       def self.fetch: (String | Symbol name, ?kind: String?) -> Definition
       def self.names: () -> Array[String]
+      def self.aliases: () -> Hash[String, String]
+      def self.overview: () -> Array[Definition]
     end
 
     class Result
@@ -300,18 +339,31 @@ module AnalyticsOps
       def headers: () -> Array[String]
       def to_h: () -> record
     end
+
+    class OverviewResult
+      MAX_REPORTS: Integer
+
+      attr_reader property_id: String
+      attr_reader reports: Array[Result]
+      attr_reader property_quota: record
+
+      def initialize: (property_id: String, reports: Array[Result]) -> void
+      def report: (String | Symbol name) -> Result
+      def to_h: () -> record
+    end
   end
 
   module Clients
     class Admin
       def initialize: (
         ?client: untyped,
-        ?credentials: untyped,
+        ?service_account: ServiceAccount?,
+        ?access: :read | :edit,
         ?transport: Symbol,
-        ?timeout: Float?,
+        ?timeout: (Integer | Float)?,
         ?logger: untyped
       ) -> void
-      def discover: () -> Array[Resources::Account]
+      def discover: (?include_streams: bool) -> Array[Resources::Account]
       def property_access: (String property_id) -> Resources::Property
       def snapshot: (String property_id) -> Snapshot
       def capabilities: () -> Hash[String, bool]
@@ -322,17 +374,68 @@ module AnalyticsOps
     class Data
       def initialize: (
         ?client: untyped,
-        ?credentials: untyped,
+        ?service_account: ServiceAccount?,
         ?transport: Symbol,
-        ?timeout: Float?,
+        ?timeout: (Integer | Float)?,
         ?logger: untyped
       ) -> void
       def run: (String property_id, Reports::Definition definition) -> Reports::Result
+      def batch: (String property_id, Array[Reports::Definition] definitions) -> Array[Reports::Result]
       def available?: () -> bool
       def compatibility: () -> record
     end
   end
 
+  class Connection
+    class Verification
+      attr_reader property: Resources::Property
+
+      def initialize: (property: Resources::Property) -> void
+      def to_h: () -> record
+    end
+
+    def initialize: (
+      ?admin: Clients::Admin?,
+      ?data: Clients::Data?,
+      ?service_account: ServiceAccount?,
+      ?transport: Symbol,
+      ?timeout: (Integer | Float)?,
+      ?logger: untyped
+    ) -> void
+    def discover: () -> Array[Resources::Account]
+    def properties: () -> Array[Resources::Account]
+    def verify: (String property_id) -> Verification
+  end
+
+  class Setup
+    class Result
+      attr_reader config_path: String
+      attr_reader profile: String
+      attr_reader property: Resources::Property
+
+      def initialize: (
+        config_path: String,
+        profile: String | Symbol,
+        property: Resources::Property,
+        created: bool
+      ) -> void
+      def created?: () -> bool
+      def status: () -> String
+      def to_h: () -> record
+    end
+
+    def initialize: (
+      connection: Connection,
+      config: String,
+      profile: String | Symbol,
+      ?property_id: String?,
+      ?noninteractive: bool,
+      ?input: untyped,
+      ?out: untyped
+    ) -> void
+    def call: () -> Result
+  end
+
   class Workspace
     class Verification
       attr_reader converged: bool
@@ -358,18 +461,18 @@ module AnalyticsOps
       ?environment: Hash[String, String],
       ?admin: Clients::Admin?,
       ?data: Clients::Data?,
-      ?credentials: untyped,
+      ?service_account: ServiceAccount?,
       ?transport: Symbol,
-      ?timeout: Float?,
+      ?timeout: (Integer | Float)?,
       ?logger: untyped
     ) -> Workspace
     def initialize: (
       desired_state: DesiredState,
       ?admin: Clients::Admin?,
       ?data: Clients::Data?,
-      ?credentials: untyped,
+      ?service_account: ServiceAccount?,
       ?transport: Symbol,
-      ?timeout: Float?,
+      ?timeout: (Integer | Float)?,
       ?logger: untyped
     ) -> void
     def discover: () -> Array[Resources::Account]
@@ -380,6 +483,7 @@ module AnalyticsOps
     def verify: () -> Verification
     def report: (String | Reports::Definition name_or_definition) -> Reports::Result
     def realtime: (?String | Reports::Definition name_or_definition) -> Reports::Result
+    def overview: () -> Reports::OverviewResult
     def doctor: () -> DoctorResult
   end
 
@@ -389,7 +493,10 @@ module AnalyticsOps
       ?out: untyped,
       ?err: untyped,
       ?input: untyped,
-      ?workspace_loader: untyped
+      ?workspace_loader: untyped,
+      ?connection_loader: untyped,
+      ?service_account_loader: untyped,
+      ?service_account_store: ServiceAccount::Store?
     ) -> Integer
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: analytics_ops
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Nelson Chaves
@@ -37,6 +37,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.9.0
+- !ruby/object:Gem::Dependency
+  name: googleauth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
 description: |-
   Analytics Ops provides configuration-as-code, drift detection, explicit
   plans, safe application, and reporting for Google Analytics 4 properties.
@@ -62,6 +76,7 @@ files:
 - docs/configuration-schema-v1.json
 - docs/configuration.md
 - docs/google-client-compatibility.md
+- docs/live-smoke-test.md
 - docs/plan-format.md
 - docs/plan-schema-v1.json
 - docs/rails.md
@@ -73,13 +88,19 @@ files:
 - lib/analytics_ops/applier.rb
 - lib/analytics_ops/canonical.rb
 - lib/analytics_ops/cli.rb
+- lib/analytics_ops/cli/options.rb
+- lib/analytics_ops/cli/presenter.rb
 - lib/analytics_ops/clients/admin.rb
+- lib/analytics_ops/clients/admin_normalization.rb
 - lib/analytics_ops/clients/data.rb
+- lib/analytics_ops/clients/error_translation.rb
 - lib/analytics_ops/configuration.rb
 - lib/analytics_ops/configuration/document.rb
 - lib/analytics_ops/configuration/loader.rb
 - lib/analytics_ops/configuration/schema.rb
 - lib/analytics_ops/configuration/validator.rb
+- lib/analytics_ops/configuration/writer.rb
+- lib/analytics_ops/connection.rb
 - lib/analytics_ops/desired_state.rb
 - lib/analytics_ops/errors.rb
 - lib/analytics_ops/plan.rb
@@ -90,8 +111,12 @@ files:
 - lib/analytics_ops/reports.rb
 - lib/analytics_ops/reports/catalog.rb
 - lib/analytics_ops/reports/definition.rb
+- lib/analytics_ops/reports/overview.rb
+- lib/analytics_ops/reports/overview_result.rb
 - lib/analytics_ops/reports/result.rb
 - lib/analytics_ops/resources.rb
+- lib/analytics_ops/service_account.rb
+- lib/analytics_ops/setup.rb
 - lib/analytics_ops/snapshot.rb
 - lib/analytics_ops/version.rb
 - lib/analytics_ops/workspace.rb