analytics_ops 0.2.0 → 0.3.0

data/lib/analytics_ops/workspace.rb

@@ -7,6 +7,8 @@ require "time"
 module AnalyticsOps
   # Primary Ruby API. Loading a workspace validates local data but performs no network calls.
   class Workspace
+    MAX_EXPORT_ROWS = 1_000_000
+    DEFAULT_PAGE_SIZE = 100_000
     # Immutable convergence result returned by verify.
     class Verification
       attr_reader :converged, :plan
@@ -42,13 +44,22 @@ module AnalyticsOps
 
     attr_reader :desired_state
 
-    def self.load(path, profile:, environment: ENV, admin: nil, data: nil, service_account: nil,
+    def self.load(path, profile:, environment: ENV, admin: nil, data: nil, bigquery: nil, service_account: nil,
                   transport: :grpc, timeout: nil, logger: nil)
       document = Configuration.load(path, environment:)
-      new(desired_state: document.profile(profile), admin:, data:, service_account:, transport:, timeout:, logger:)
+      new(
+        desired_state: document.profile(profile),
+        admin:,
+        data:,
+        bigquery:,
+        service_account:,
+        transport:,
+        timeout:,
+        logger:
+      )
     end
 
-    def initialize(desired_state:, admin: nil, data: nil, service_account: nil,
+    def initialize(desired_state:, admin: nil, data: nil, bigquery: 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"
@@ -58,6 +69,7 @@ module AnalyticsOps
       @admin = admin
       @injected_admin = admin
       @data = data
+      @bigquery = bigquery
       @service_account = service_account
       @transport = transport
       @timeout = timeout
@@ -90,21 +102,150 @@ module AnalyticsOps
       Verification.new(plan:)
     end
 
-    def report(name_or_definition)
-      definition = report_definition(name_or_definition, kind: "standard")
+    def report(name_or_definition, date_ranges: nil)
+      definition, custom = resolved_report_definition(name_or_definition, kind: "standard")
+      definition = definition.with_date_ranges(date_ranges) if date_ranges
+      validate_report_definition(definition) if custom
       data.run(desired_state.property_id, definition)
     end
 
     def realtime(name_or_definition = "realtime_events")
-      definition = report_definition(name_or_definition, kind: "realtime")
+      definition, custom = resolved_report_definition(name_or_definition, kind: "realtime")
+      validate_report_definition(definition) if custom
       data.run(desired_state.property_id, definition)
     end
 
-    def overview
-      reports = data.batch(desired_state.property_id, Reports::Catalog.overview)
+    def report_metadata(query: nil, kind: nil)
+      fields = data.metadata(desired_state.property_id).search(query, kind:)
+      Reports::FieldList.new(property_id: desired_state.property_id, query:, kind: kind&.to_s, fields:)
+    end
+
+    def report_recipes
+      built_in = Reports::Catalog.names.map do |name|
+        definition = Reports::Catalog.fetch(name)
+        Reports::Recipe.new(
+          name:,
+          kind: definition.kind,
+          source: "built_in",
+          dimensions: definition.dimensions,
+          metrics: definition.metrics
+        )
+      end
+      configured = desired_state.reports.map do |name, definition|
+        Reports::Recipe.new(
+          name:,
+          kind: definition.kind,
+          source: "configuration",
+          dimensions: definition.dimensions,
+          metrics: definition.metrics
+        )
+      end
+      Reports::RecipeList.new(recipes: (built_in + configured).sort_by { |recipe| [recipe.name, recipe.source] })
+    end
+
+    def report_compatibility(name_or_definition)
+      definition, = resolved_report_definition(name_or_definition, kind: "standard")
+      validate_report_fields!(definition)
+      data.check_compatibility(desired_state.property_id, definition)
+    end
+
+    def each_report_page(name_or_definition, date_ranges: nil, page_size: DEFAULT_PAGE_SIZE,
+                         max_rows: MAX_EXPORT_ROWS)
+      return enum_for(__method__, name_or_definition, date_ranges:, page_size:, max_rows:) unless block_given?
+
+      definition, custom = resolved_report_definition(name_or_definition, kind: "standard")
+      definition = definition.with_date_ranges(date_ranges) if date_ranges
+      validate_report_definition(definition) if custom
+      page_size = bounded_integer(page_size, "page_size", maximum: Reports::Definition::MAX_STANDARD_LIMIT)
+      max_rows = bounded_integer(max_rows, "max_rows", maximum: MAX_EXPORT_ROWS)
+
+      offset = definition.offset
+      ending_offset = offset + max_rows
+      while offset < ending_offset
+        requested = [page_size, ending_offset - offset].min
+        result = data.run(
+          desired_state.property_id,
+          definition.with_pagination(offset:, limit: requested)
+        )
+        yield result
+        returned = result.rows.length
+        break if returned.zero? || offset + returned >= result.row_count
+
+        offset += returned
+      end
+    end
+
+    def export_report(name_or_definition, path:, date_ranges: nil, page_size: DEFAULT_PAGE_SIZE,
+                      max_rows: MAX_EXPORT_ROWS)
+      pages = each_report_page(name_or_definition, date_ranges:, page_size:, max_rows:)
+      Reports::CSVExport.write(path, pages)
+    end
+
+    def overview(date_ranges: nil)
+      definitions = Reports::Catalog.overview
+      definitions = definitions.map { |definition| definition.with_date_ranges(date_ranges) }.freeze if date_ranges
+      reports = data.batch(desired_state.property_id, definitions)
       Reports::OverviewResult.new(property_id: desired_state.property_id, reports:)
     end
 
+    def health(date_ranges: nil)
+      ranges = date_ranges || Reports::Period.resolve(last_days: Reports::Period::DEFAULT_DAYS, compare: true)
+      Health.validate_date_ranges!(ranges)
+      definitions = Health::Definitions.for(ranges)
+      reports = data.batch(desired_state.property_id, definitions)
+      current_snapshot = snapshot
+      current_plan = Planner.new(desired_state:, snapshot: current_snapshot).call
+      Health::Runner.new(
+        desired_state:,
+        reports:,
+        plan: current_plan,
+        date_ranges: ranges
+      ).call
+    end
+
+    def governance
+      remote = admin.governance_snapshot(desired_state.property_id)
+      Governance::Auditor.new(snapshot: remote, settings: desired_state.governance).call
+    end
+
+    def change_history(limit: 100, days: 30)
+      edit_admin.change_history(desired_state.property_id, limit:, days:)
+    end
+
+    def access_report(date_ranges: nil, limit: 1_000)
+      ranges = date_ranges || Reports::Period.resolve(last_days: Reports::Period::DEFAULT_DAYS, compare: false)
+      admin.access_report(desired_state.property_id, date_ranges: ranges, limit:)
+    end
+
+    def raw_report(name, date_ranges: nil, limit: 1_000)
+      settings = desired_state.bigquery
+      unless settings
+        raise ConfigurationError,
+              "BigQuery is not configured for this profile; see docs/bigquery.md"
+      end
+      ranges = date_ranges || Reports::Period.resolve(last_days: Reports::Period::DEFAULT_DAYS, compare: false)
+      definition = BigQuery::Definition.from_date_ranges(name, ranges, limit:)
+      bigquery_client.run(definition)
+    end
+
+    def funnel(name, date_ranges: nil)
+      definition = desired_state.funnels.fetch(name.to_s) do
+        available = desired_state.funnels.keys.sort.join(", ")
+        raise InvalidRequestError, "Unknown funnel #{name.inspect}; available funnels: #{available}"
+      end
+      unless desired_state.bigquery
+        raise UnsupportedCapabilityError,
+              "Funnel reports currently require the optional BigQuery configuration"
+      end
+      ranges = date_ranges || Reports::Period.resolve(last_days: Reports::Period::DEFAULT_DAYS, compare: false)
+      dates = BigQuery::Definition.from_date_ranges("event_counts", ranges, limit: 1)
+      bigquery_client.run_funnel(
+        definition,
+        start_suffix: dates.start_suffix,
+        end_suffix: dates.end_suffix
+      )
+    end
+
     def doctor
       remote = snapshot
       checks = [
@@ -114,6 +255,7 @@ module AnalyticsOps
         { "name" => "admin_api", "status" => "ok", "detail" => "Admin API read succeeded" },
         { "name" => "property_access", "status" => "ok", "detail" => "Read properties/#{remote.property_id}" }
       ]
+      checks.concat(credential_file_checks)
       checks.concat(compatibility_checks)
       checks << clock_check
       checks << edit_capability_check
@@ -167,6 +309,18 @@ module AnalyticsOps
       )
     end
 
+    def bigquery_client
+      return @bigquery if @bigquery
+
+      require_relative "bigquery"
+      @bigquery = Clients::BigQuery.new(
+        settings: desired_state.bigquery,
+        service_account:,
+        timeout: @timeout,
+        logger: @logger
+      )
+    end
+
     def service_account
       @service_account ||= ServiceAccount.load
     end
@@ -182,6 +336,27 @@ module AnalyticsOps
       end
     end
 
+    def credential_file_checks
+      return [] unless @service_account
+
+      warnings = @service_account.security_warnings
+      if warnings.empty?
+        return [{
+          "name" => "credential_file_security",
+          "status" => "ok",
+          "detail" => "Service-account key permissions and storage location look safe"
+        }]
+      end
+
+      warnings.each_with_index.map do |warning, index|
+        {
+          "name" => "credential_file_security_#{index + 1}",
+          "status" => "warning",
+          "detail" => warning
+        }
+      end
+    end
+
     def clock_check
       now = Time.now.utc
       plausible = now.year.between?(2024, 2100)
@@ -215,9 +390,14 @@ module AnalyticsOps
       )
     end
 
-    def report_definition(name_or_definition, kind:)
+    def resolved_report_definition(name_or_definition, kind:)
+      custom = false
       definition = if name_or_definition.is_a?(Reports::Definition)
+                     custom = true
                      name_or_definition
+                   elsif desired_state.reports.key?(name_or_definition.to_s)
+                     custom = true
+                     desired_state.reports.fetch(name_or_definition.to_s)
                    else
                      Reports::Catalog.fetch(name_or_definition, kind:)
                    end
@@ -225,7 +405,39 @@ module AnalyticsOps
         raise InvalidRequestError, "Report #{definition.name} is #{definition.kind}, not #{kind}"
       end
 
-      definition
+      [definition, custom]
+    end
+
+    def validate_report_definition(definition)
+      validate_report_fields!(definition)
+      return if definition.realtime?
+
+      compatibility = data.check_compatibility(desired_state.property_id, definition)
+      return if compatibility.compatible
+
+      incompatible = (compatibility.dimensions + compatibility.metrics).reject do |entry|
+        entry.fetch("compatibility") == "compatible"
+      end
+      names = incompatible.map { |entry| entry.fetch("api_name") }.join(", ")
+      raise InvalidRequestError, "Report fields are not compatible for this property: #{names}"
+    end
+
+    def validate_report_fields!(definition)
+      metadata = data.metadata(desired_state.property_id)
+      available_dimensions = metadata.dimensions.map(&:api_name)
+      available_metrics = metadata.metrics.map(&:api_name)
+      missing_dimensions = definition.dimensions - available_dimensions
+      missing_metrics = definition.metrics - available_metrics
+      return if missing_dimensions.empty? && missing_metrics.empty?
+
+      missing = (missing_dimensions + missing_metrics).join(", ")
+      raise InvalidRequestError, "Unknown report fields for this property: #{missing}"
+    end
+
+    def bounded_integer(value, label, maximum:)
+      return value if value.is_a?(Integer) && value.between?(1, maximum)
+
+      raise InvalidRequestError, "#{label} must be between 1 and #{maximum}"
     end
 
     def validate_plan_target!(saved_plan)

data/lib/analytics_ops.rb

@@ -1,11 +1,15 @@
 # frozen_string_literal: true
 
 require_relative "analytics_ops/version"
-require_relative "analytics_ops/errors"
 require_relative "analytics_ops/redaction"
+require_relative "analytics_ops/errors"
 require_relative "analytics_ops/service_account"
 require_relative "analytics_ops/canonical"
 require_relative "analytics_ops/resources"
+require_relative "analytics_ops/reports"
+require_relative "analytics_ops/bigquery/definition"
+require_relative "analytics_ops/funnels"
+require_relative "analytics_ops/governance"
 require_relative "analytics_ops/desired_state"
 require_relative "analytics_ops/configuration"
 require_relative "analytics_ops/snapshot"
@@ -13,12 +17,13 @@ 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/health"
 require_relative "analytics_ops/connection"
 require_relative "analytics_ops/setup"
 require_relative "analytics_ops/applier"
 require_relative "analytics_ops/workspace"
+require_relative "analytics_ops/portfolio"
 
 # Safe Google Analytics 4 configuration and reporting operations.
 module AnalyticsOps

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

@@ -2,7 +2,7 @@
 version: 1
 
 profiles:
-  development:
+  production:
     # GA4 property ID (numeric), not an account ID, stream ID, or measurement ID.
     property_id: "${GA4_PROPERTY_ID}"