analytics_ops 0.1.0

data/docs/plan-schema-v1.json

@@ -0,0 +1,224 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/nelsonchaves/analytics_ops/blob/master/docs/plan-schema-v1.json",
+  "title": "Analytics Ops saved plan version 1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["format_version", "profile", "property_id", "snapshot_fingerprint", "changes", "findings"],
+  "properties": {
+    "format_version": { "const": 1 },
+    "profile": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$" },
+    "property_id": { "$ref": "#/$defs/id" },
+    "snapshot_fingerprint": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "changes": {
+      "type": "array",
+      "maxItems": 10000,
+      "items": { "$ref": "#/$defs/change" }
+    },
+    "findings": {
+      "type": "array",
+      "maxItems": 10000,
+      "items": { "$ref": "#/$defs/finding" }
+    }
+  },
+  "$defs": {
+    "id": { "type": "string", "pattern": "^[0-9]{1,50}$" },
+    "text": { "type": "string", "pattern": "^[^\\u0000-\\u001F\\u007F]{1,500}$" },
+    "resourceName": {
+      "type": "string",
+      "pattern": "^properties/[0-9]{1,50}/[A-Za-z]+(?:/[A-Za-z0-9_-]+)?$"
+    },
+    "change": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "resource_type", "resource_identity", "operation", "api_maturity",
+        "before", "after", "reversible", "rollback"
+      ],
+      "properties": {
+        "resource_type": {
+          "enum": ["data_stream", "retention", "key_event", "custom_dimension", "custom_metric"]
+        },
+        "resource_identity": { "$ref": "#/$defs/text" },
+        "operation": { "enum": ["create", "update"] },
+        "api_maturity": { "enum": ["stable", "beta", "experimental"] },
+        "before": { "type": ["object", "null"] },
+        "after": { "type": "object" },
+        "reversible": { "type": "boolean" },
+        "rollback": { "$ref": "#/$defs/text" }
+      },
+      "oneOf": [
+        {
+          "properties": {
+            "resource_type": { "const": "data_stream" },
+            "resource_identity": { "pattern": "^stream:[0-9]{1,50}$" },
+            "operation": { "const": "update" },
+            "before": { "$ref": "#/$defs/dataStream" },
+            "after": { "$ref": "#/$defs/dataStream" }
+          }
+        },
+        {
+          "properties": {
+            "resource_type": { "const": "retention" },
+            "resource_identity": { "pattern": "^property:[0-9]{1,50}:retention$" },
+            "operation": { "const": "update" },
+            "before": { "$ref": "#/$defs/retention" },
+            "after": { "$ref": "#/$defs/retention" }
+          }
+        },
+        {
+          "properties": {
+            "resource_type": { "const": "key_event" },
+            "resource_identity": { "pattern": "^event:[A-Za-z][A-Za-z0-9_]{0,39}$" },
+            "operation": { "const": "create" },
+            "before": { "type": "null" },
+            "after": { "$ref": "#/$defs/keyEvent" }
+          }
+        },
+        {
+          "properties": {
+            "resource_type": { "const": "custom_dimension" },
+            "resource_identity": { "pattern": "^(?:event|user|item):[A-Za-z][A-Za-z0-9_]{0,39}$" },
+            "operation": { "const": "create" },
+            "before": { "type": "null" },
+            "after": { "$ref": "#/$defs/customDimensionCreate" }
+          }
+        },
+        {
+          "properties": {
+            "resource_type": { "const": "custom_dimension" },
+            "resource_identity": { "pattern": "^(?:event|user|item):[A-Za-z][A-Za-z0-9_]{0,39}$" },
+            "operation": { "const": "update" },
+            "before": { "$ref": "#/$defs/customDimensionUpdate" },
+            "after": { "$ref": "#/$defs/customDimensionUpdate" }
+          }
+        },
+        {
+          "properties": {
+            "resource_type": { "const": "custom_metric" },
+            "resource_identity": { "pattern": "^[A-Za-z][A-Za-z0-9_]{0,39}$" },
+            "operation": { "const": "create" },
+            "before": { "type": "null" },
+            "after": { "$ref": "#/$defs/customMetricCreate" }
+          }
+        },
+        {
+          "properties": {
+            "resource_type": { "const": "custom_metric" },
+            "resource_identity": { "pattern": "^[A-Za-z][A-Za-z0-9_]{0,39}$" },
+            "operation": { "const": "update" },
+            "before": { "$ref": "#/$defs/customMetricUpdate" },
+            "after": { "$ref": "#/$defs/customMetricUpdate" }
+          }
+        }
+      ]
+    },
+    "finding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["severity", "code", "resource_identity", "message"],
+      "properties": {
+        "severity": { "enum": ["drift", "manual", "experimental", "warning"] },
+        "code": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$" },
+        "resource_identity": { "$ref": "#/$defs/text" },
+        "message": { "type": "string", "pattern": "^[^\\u0000-\\u001F\\u007F]{1,1000}$" }
+      }
+    },
+    "dataStream": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "name", "display_name", "type", "default_uri", "measurement_id"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "name": { "$ref": "#/$defs/resourceName" },
+        "display_name": { "type": "string", "maxLength": 100 },
+        "type": { "enum": ["web", "android", "ios", "unspecified"] },
+        "default_uri": { "type": ["string", "null"], "format": "uri" },
+        "measurement_id": { "type": ["string", "null"], "maxLength": 64 }
+      }
+    },
+    "retention": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "event_data", "user_data", "reset_on_new_activity"],
+      "properties": {
+        "name": { "$ref": "#/$defs/resourceName" },
+        "event_data": { "$ref": "#/$defs/retentionValue" },
+        "user_data": { "$ref": "#/$defs/retentionValue" },
+        "reset_on_new_activity": { "type": "boolean" }
+      }
+    },
+    "retentionValue": {
+      "enum": ["2_months", "14_months", "26_months", "38_months", "50_months"]
+    },
+    "keyEvent": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["event_name", "counting_method"],
+      "properties": {
+        "event_name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,39}$" },
+        "counting_method": { "enum": ["once_per_event", "once_per_session"] }
+      }
+    },
+    "customDimensionCreate": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["parameter_name", "display_name", "description", "scope", "disallow_ads_personalization"],
+      "properties": {
+        "parameter_name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,39}$" },
+        "display_name": { "type": "string", "minLength": 1, "maxLength": 82 },
+        "description": { "type": "string", "maxLength": 150 },
+        "scope": { "enum": ["event", "user", "item"] },
+        "disallow_ads_personalization": { "type": "boolean" }
+      }
+    },
+    "customDimensionUpdate": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "parameter_name", "display_name", "description", "scope", "disallow_ads_personalization"],
+      "properties": {
+        "name": { "$ref": "#/$defs/resourceName" },
+        "parameter_name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,39}$" },
+        "display_name": { "type": "string", "minLength": 1, "maxLength": 82 },
+        "description": { "type": "string", "maxLength": 150 },
+        "scope": { "enum": ["event", "user", "item"] },
+        "disallow_ads_personalization": { "type": "boolean" }
+      }
+    },
+    "customMetricCreate": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["parameter_name", "display_name", "description", "scope", "measurement_unit"],
+      "properties": {
+        "parameter_name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,39}$" },
+        "display_name": { "type": "string", "minLength": 1, "maxLength": 82 },
+        "description": { "type": "string", "maxLength": 150 },
+        "scope": { "const": "event" },
+        "measurement_unit": {
+          "enum": [
+            "standard", "currency", "feet", "meters", "kilometers", "miles",
+            "milliseconds", "seconds", "minutes", "hours"
+          ]
+        }
+      }
+    },
+    "customMetricUpdate": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "parameter_name", "display_name", "description", "scope", "measurement_unit"],
+      "properties": {
+        "name": { "$ref": "#/$defs/resourceName" },
+        "parameter_name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,39}$" },
+        "display_name": { "type": "string", "minLength": 1, "maxLength": 82 },
+        "description": { "type": "string", "maxLength": 150 },
+        "scope": { "const": "event" },
+        "measurement_unit": {
+          "enum": [
+            "standard", "currency", "feet", "meters", "kilometers", "miles",
+            "milliseconds", "seconds", "minutes", "hours"
+          ]
+        }
+      }
+    }
+  }
+}

data/docs/rails.md

@@ -0,0 +1,73 @@
+# Rails integration
+
+Rails support is optional and lives behind:
+
+```ruby
+# Gemfile
+gem "analytics_ops", require: "analytics_ops/rails", group: :development
+```
+
+It supports Rails 7.2, 8.0, and 8.1. The core gem does not depend on Rails or
+Active Support.
+
+## Install
+
+```bash
+bundle install
+bin/rails generate analytics_ops:install
+```
+
+The generator creates only:
+
+- `config/analytics_ops.yml`
+- `bin/analytics-ops` with executable mode
+
+The generated file has a `development` profile and fake-safe placeholders.
+Add a profile matching the Rails environment you intend to operate, or set
+`ANALYTICS_OPS_PROFILE`.
+
+## Rake tasks
+
+```bash
+bin/rake analytics:doctor
+bin/rake analytics:audit
+bin/rake analytics:plan
+bin/rake analytics:verify
+bin/rake 'analytics:report[traffic_acquisition]'
+```
+
+`analytics:plan` writes `tmp/analytics_ops-plan.json`. Override task inputs
+without changing application code:
+
+```bash
+ANALYTICS_OPS_PROFILE=production \
+ANALYTICS_OPS_CONFIG=config/analytics_ops.yml \
+ANALYTICS_OPS_PLAN=tmp/production-ga4-plan.json \
+bin/rake analytics:plan
+```
+
+There is intentionally no `analytics:apply` Rake task. Apply a reviewed file
+with the explicit CLI:
+
+```bash
+bin/analytics-ops apply tmp/production-ga4-plan.json
+```
+
+## Runtime boundary
+
+The integration is a Railtie, not an Engine. It has no:
+
+- models or database
+- migrations
+- routes or controllers
+- views or helpers
+- assets or JavaScript
+- browser tag injection
+
+Requiring `analytics_ops/rails`, booting Rails, and registering Rake tasks do
+not construct Google clients or make network requests. A network call begins
+only when an operator invokes a task or CLI operation.
+
+Do not place production mutation credentials in a Rails web container.
+Scheduled audits may use a dedicated read-only identity. Interactive apply
+belongs on an administrator workstation or in a protected release workflow.

data/docs/reports.md

@@ -0,0 +1,124 @@
+# Reports
+
+Reports are read-only Data API calls. Analytics Ops validates an immutable
+definition, sends an official-client request, and returns a gem-owned
+`AnalyticsOps::Reports::Result`.
+
+## Built-in recipes
+
+All standard recipes cover the previous 28 complete days
+(`28daysAgo` through `yesterday`).
+
+| Name | What it answers | Required custom definitions |
+| --- | --- | --- |
+| `traffic_acquisition` | Sessions, users, and key events by channel/source/medium | None |
+| `landing_pages` | Sessions, users, and key events by landing page | None |
+| `calculator_completions` | Completed calculations by calculator | `customEvent:calculator_slug` |
+| `shares_and_prints` | Share and print events by calculator | `customEvent:calculator_slug` |
+| `related_calculator_navigation` | Related-calculator clicks by source and destination | `customEvent:calculator_slug`, `customEvent:related_calculator_slug` |
+| `commercial_outbound_clicks` | Commercial outbound clicks by calculator and destination | `customEvent:calculator_slug`, `customEvent:outbound_destination` |
+| `realtime_events` | Event count and active users by event name | None |
+
+The event names used by the calculator recipes are
+`calculation_completed`, `result_shared`, `result_printed`,
+`related_calculator_clicked`, and `commercial_outbound_clicked`.
+If your site uses different names, create a custom Ruby definition.
+
+## CLI
+
+```bash
+analytics-ops report traffic_acquisition
+analytics-ops report landing_pages --format json
+analytics-ops report calculator_completions --format csv
+analytics-ops realtime
+```
+
+CSV is accepted only for `report` and `realtime`. The CSV renderer protects
+cells that start with `=`, `+`, `-`, or `@` from spreadsheet formula
+execution.
+
+## Ruby
+
+```ruby
+workspace = AnalyticsOps::Workspace.load(
+  "config/analytics_ops.yml",
+  profile: "production"
+)
+
+result = workspace.report("traffic_acquisition")
+puts result.headers
+puts result.rows
+puts result.metadata
+```
+
+Custom immutable definition:
+
+```ruby
+definition = AnalyticsOps::Reports::Definition.new(
+  name: "recent_events",
+  kind: "standard",
+  dimensions: ["eventName"],
+  metrics: ["eventCount"],
+  date_ranges: [
+    { "start_date" => "7daysAgo", "end_date" => "yesterday" }
+  ],
+  dimension_filter: {
+    "field" => "eventName",
+    "match_type" => "begins_with",
+    "value" => "calculator_",
+    "case_sensitive" => false
+  },
+  order_bys: [
+    { "metric" => "eventCount", "desc" => true }
+  ],
+  limit: 100
+)
+
+result = workspace.report(definition)
+```
+
+Definitions reject unknown fields, malformed names, duplicate dimensions or
+metrics, invalid date order, filters that reference unselected fields,
+non-finite numeric filters, invalid ordering, and unbounded limits. Realtime
+definitions cannot use date ranges or offsets.
+
+## Result shape
+
+`result.to_h` contains:
+
+- `name` and `kind`
+- separate dimension and metric headers
+- rows keyed by header name
+- Google's total `row_count`
+- response metadata when present, including thresholding, sampling, time zone,
+  currency, empty reason, and property quota
+
+Metric values remain strings, matching the Data API wire contract. Generated
+Google types never escape the adapter.
+
+## GA reporting limits
+
+A GA4 report is not an exact count of all site activity:
+
+- It covers only traffic collected under your site's consent and tagging
+  behavior. This gem does not inject tags or manage consent.
+- Google may apply data thresholds, sampling, cardinality limits, modeled data,
+  attribution rules, or an `(other)` row.
+- Standard reports can lag behind collection; realtime is short-lived and is
+  useful for verification, not accounting.
+- Data API results can differ from the Analytics UI because the selected
+  dimensions, metrics, filters, identity, and attribution semantics differ.
+- Quotas belong to Google and can change. Analytics Ops returns quota metadata
+  when Google supplies it.
+- Custom dimensions must already be registered and populated. Their Data API
+  names use `customEvent:parameter_name`.
+
+Do not treat report output as billing, audit, or consent evidence. Avoid
+personally identifiable or user-level dimensions, and review exported CSV/JSON
+as potentially sensitive operational data.
+
+Official references:
+
+- [Data API reporting](https://developers.google.com/analytics/devguides/reporting/data/v1)
+- [Reporting data expectations](https://developers.google.com/analytics/devguides/reporting/data/v1/data-expectations)
+- [API dimensions and metrics](https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema)

data/docs/safety.md

@@ -0,0 +1,93 @@
+# Safety
+
+Analytics Ops is read-only unless you explicitly apply a saved plan.
+
+## What cannot mutate
+
+`doctor`, `discover`, `snapshot`, `audit`, `plan`, `verify`,
+`report`, and `realtime` only read Google APIs. Loading the gem, parsing
+YAML, and booting Rails make no network request.
+
+## What apply requires
+
+An apply needs all of these:
+
+1. A saved version-1 JSON plan.
+2. A configuration profile matching the plan's profile and property ID.
+3. Explicit confirmation—typed `yes`, or both `--non-interactive --yes`.
+4. A fresh remote snapshot with the exact saved fingerprint.
+
+The applier executes only the operations stored in the file. It never replans
+during apply and never turns findings into changes.
+
+## Stale plans
+
+Every plan fingerprints normalized managed remote state with SHA-256. If that
+state changed after planning, apply exits 79 without performing any saved
+operation:
+
+```text
+StalePlanError: Remote state changed after this plan was generated; create a new plan
+```
+
+Generate and review a new plan. Do not edit the fingerprint to force a stale
+plan through.
+
+## Destructive operations
+
+Ordinary plans contain only supported creates and updates. They never:
+
+- delete an account, property, stream, key event, dimension, or metric
+- archive a custom definition
+- delete an unmanaged resource
+- recreate an immutable conflict
+- create a missing stream automatically
+
+Configuration removal does not mean remote deletion. It simply stops managing
+that declaration.
+
+## Partial apply and rollback
+
+Apply stops on the first failed operation. Exit 80 includes:
+
+- successfully applied changes
+- the failed change and redacted error
+- unattempted remaining changes
+
+Analytics Ops does not attempt an automatic rollback because rollback itself
+can fail or overwrite concurrent operator work. Each change includes a
+human-readable rollback instruction. Reconcile the remote state, then generate
+a fresh plan. Never reuse the old fingerprint.
+
+Some create rollbacks require a deliberate manual delete or archive in Google
+Analytics. Those destructive actions are outside the ordinary CLI.
+
+## Plan-file defenses
+
+Saved plans are deterministic JSON, limited to 1 MiB, and written atomically
+with mode 0600. Loading rejects:
+
+- unknown or missing fields
+- duplicate JSON keys
+- incorrect scalar types
+- invalid resource identities
+- unknown resource payload fields
+- unsupported operations
+- no-op updates and immutable-field changes
+- secret-shaped fields and control characters
+- resource names for another property
+
+Workspace and adapter checks provide additional cross-property protection.
+The public schema is [plan-schema-v1.json](plan-schema-v1.json).
+
+## Credential and data boundaries
+
+- Credentials never belong in YAML, plans, fixtures, logs, or command output.
+- Report rows are never logged automatically.
+- The gem has no telemetry and stores no report results.
+- The gem does not inject browser analytics or manage consent.
+- Production mutation credentials should not exist in a Rails web container.
+- Real production IDs and exports do not belong in repository fixtures.
+
+Use a read-only identity for routine audits and reports. Use a separately
+protected edit identity only for a reviewed apply.

data/docs/troubleshooting.md

@@ -0,0 +1,103 @@
+# Troubleshooting
+
+Start with:
+
+```bash
+analytics-ops doctor --format json
+```
+
+The command is read-only and checks both Google APIs.
+
+## Configuration error
+
+```text
+ConfigurationError: ... property_id must be a numeric identifier encoded as a string
+```
+
+Quote numeric IDs:
+
+```yaml
+property_id: "123456789"
+stream_id: "987654321"
+```
+
+Do not use account ID `100000001` or measurement ID `G-EXAMPLE1` in those
+fields. Unknown keys, ERB, YAML aliases, missing environment variables, and
+secret-shaped fields are intentionally rejected.
+
+## Authentication failure (exit 66)
+
+Create ADC again and ensure both APIs are enabled:
+
+```bash
+gcloud auth application-default login \
+  --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.readonly"
+```
+
+If `GOOGLE_APPLICATION_CREDENTIALS` is set, confirm that it points to the
+intended local credential file. Never add that path or file to configuration
+or source control.
+
+## Permission failure (exit 77)
+
+The Google identity needs access inside the GA4 property. Cloud IAM alone is
+not enough. Add the user or service-account identity to the property with a
+read role; use an edit-capable role only for plan application.
+
+Use `analytics-ops discover` to see accessible numeric property IDs.
+
+## API or remote failure (exit 69)
+
+Confirm that the Google Analytics Admin API and Data API are enabled in the
+credential's Cloud project. Check the configuration ID and the error's typed
+message. Invalid dimensions, metrics, custom definitions, or property
+restrictions can also produce this status.
+
+## Quota (exit 75) or timeout (exit 74)
+
+Wait for Google quota to recover, reduce report frequency, or use a positive
+`--timeout`. Do not blindly retry an apply after an uncertain response;
+snapshot and replan so remote state is reconciled first.
+
+## Drift status 2
+
+This is expected automation behavior, not a crash. `audit` and `verify`
+return 2 when managed state differs or a drift finding remains.
+
+## Stale plan (exit 79)
+
+Someone or something changed relevant remote state after the plan was created.
+Generate a new plan, review it, and apply that new file. Never edit the saved
+fingerprint.
+
+## Partial apply (exit 80)
+
+Read the reconciliation output. It lists applied, failed, and unattempted
+operations. Verify the property, perform any deliberate manual rollback, then
+generate a new plan. Do not rerun the old plan.
+
+## A custom report fails
+
+Confirm every requested dimension and metric is compatible and registered.
+Event-scoped custom fields use names such as
+`customEvent:calculator_slug`. Standard reports require a date range;
+realtime reports reject date ranges and offsets.
+
+Google thresholding, sampling, consent coverage, cardinality, and processing
+delay can explain an empty or lower-than-expected result. Inspect
+`result.metadata` in JSON output.
+
+## Rails task cannot find a profile
+
+Rails tasks default to `Rails.env`. The generator creates a
+`development` profile. Add the intended profile or override it:
+
+```bash
+ANALYTICS_OPS_PROFILE=production bin/rake analytics:doctor
+```
+
+## Report a problem safely
+
+Include the gem version, Ruby version, command name, exit status, and a minimal
+configuration with obviously fake IDs. Do not include credentials, tokens,
+authorization headers, real report rows, production plans, or private keys.

data/exe/analytics-ops

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "analytics_ops/cli"
+
+exit AnalyticsOps::CLI.start(ARGV)

data/lib/analytics_ops/applier.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# Explicit saved-plan application.
+
+module AnalyticsOps
+  # Executes only the operations contained in an approved, non-stale plan.
+  class Applier
+    # Immutable success or partial-reconciliation summary.
+    class Result < Resources::Value
+      fields :status, :applied, :failed, :remaining
+    end
+
+    def initialize(admin:)
+      @admin = admin
+    end
+
+    def call(plan, confirm: false)
+      raise ConfirmationRequiredError, "Applying a plan requires explicit confirmation" unless confirm
+
+      current = @admin.snapshot(plan.property_id)
+      unless current.fingerprint == plan.snapshot_fingerprint
+        raise StalePlanError, "Remote state changed after this plan was generated; create a new plan"
+      end
+
+      applied = []
+      plan.changes.each_with_index do |change, index|
+        @admin.apply_change(change, property_id: plan.property_id)
+        applied << change.to_h
+      rescue StandardError => error
+        result = Result.new(
+          status: "partial",
+          applied:,
+          failed: failure(change, error),
+          remaining: plan.changes.drop(index + 1).map(&:to_h)
+        )
+        raise PartialApplyError.new("Apply stopped after #{applied.length} successful changes", result:)
+      end
+
+      Result.new(status: "applied", applied:, failed: nil, remaining: [])
+    end
+
+    private
+
+    def failure(change, error)
+      {
+        "change" => change.to_h,
+        "error_type" => error.class.name,
+        "message" => Redaction.message(error.message).slice(0, 500)
+      }
+    end
+  end
+end