analytics_ops 0.1.0 → 0.2.0

data/docs/authentication.md

@@ -1,86 +1,147 @@
 # Authentication
 
-Analytics Ops uses [Google Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials)
-through Google's official Ruby clients. It does not implement OAuth, store
-tokens, or accept credential fields in configuration.
+Analytics Ops supports one authentication method: a Google service-account
+JSON key.
+
+It does not use `gcloud`, browser login, Desktop OAuth, Application Default
+Credentials, `GOOGLE_APPLICATION_CREDENTIALS`, or API keys.
+
+## One-time setup
+
+You need a Google Cloud project only to own the service account, enable the two
+Analytics APIs, and supply API quota. It does not need to be the project that
+hosts your website.
+
+1. In the Cloud project, enable:
+   - Google Analytics Admin API
+   - Google Analytics Data API
+2. Open [Google Cloud service accounts](https://console.cloud.google.com/iam-admin/serviceaccounts).
+3. Create a service account named **Analytics Ops Local**. Do not grant broad
+   Cloud IAM roles.
+4. Open the service account, choose **Keys**, create a JSON key, and save it
+   outside every source repository.
+5. Copy the service-account email, such as
+   `analytics-ops@example-project.iam.gserviceaccount.com`.
+6. In GA4, open **Admin → Account access management → Add users**.
+7. Add the service-account email:
+   - **Viewer** is enough for reports, discovery, snapshots, and audits.
+   - **Editor** is required if this identity will apply reviewed changes.
+8. Connect Analytics Ops:
 
-## Local read-only use
+```bash
+analytics-ops setup \
+  --service-account /absolute/path/to/service-account.json
+```
 
-Use an identity that has read access to the target GA4 property:
+Setup verifies both APIs, lists the GA4 properties available to the service
+account, lets you select one, and creates `config/analytics_ops.yml`.
+
+After that, use normal commands without another credential option:
 
 ```bash
-gcloud auth application-default login \
-  --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.readonly"
+analytics-ops overview
+analytics-ops report traffic
+analytics-ops realtime
+analytics-ops audit
 ```
 
-Enable both APIs in the Google Cloud project used for authentication:
+## What Analytics Ops remembers
+
+Analytics Ops writes this user-level file:
 
-- Google Analytics Admin API
-- Google Analytics Data API
+```text
+~/.config/analytics_ops/connection.json
+```
+
+It contains only the absolute path to the service-account key. The connection
+file is created atomically with mode `0600`, and its directory uses mode
+`0700`. Analytics Ops does not copy the key or place its contents in project
+configuration.
 
-Then run:
+Keep the key in a stable location. Moving or deleting it requires setup again:
 
 ```bash
-analytics-ops doctor
+analytics-ops setup \
+  --service-account /new/absolute/path/to/service-account.json
 ```
 
-`doctor` makes small read-only calls to both APIs. It confirms that Google
-accepts the credentials and that the property can be read. The installed
-clients do not expose a reliable contract for inspecting the scopes inside an
-already-issued token, so `doctor` reports scope inspection as `unknown`
-instead of guessing.
+One service account can access several GA4 accounts. Add the same
+service-account email at account level in each GA4 account.
+
+## Read and edit access
+
+Normal commands request only Google's `analytics.readonly` scope. The guarded
+`apply` command requests `analytics.edit` in addition to read access.
 
-## Applying changes
+Scopes do not grant GA4 access by themselves. The service account must also
+have the matching Viewer or Editor role in GA4 Access Management.
 
-Read-only credentials cannot apply a plan. Use a separately protected identity
-with the `analytics.edit` scope and sufficient access to the GA4 property:
+Analytics Ops still requires a saved plan, explicit confirmation, and a fresh
+matching snapshot before any apply. Merely configuring an Editor identity
+does not cause writes.
+
+## Automation
+
+Use the same service-account setup non-interactively:
 
 ```bash
-gcloud auth application-default login \
-  --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/analytics.edit"
+analytics-ops setup \
+  --service-account /secure/path/service-account.json \
+  --property 123456789 \
+  --non-interactive \
+  --json
 ```
 
-Keep mutation credentials out of a deployed Rails web container. Apply plans
-from an administrator workstation or a protected release job.
+Keep the JSON key in the CI platform's protected secret-file storage. Never
+put its contents in an environment variable, command argument, repository, or
+build log.
 
-## Automation
+## Ruby API
 
-Prefer one of these:
+The Ruby API can use an explicit service account without changing the saved
+user connection:
 
-- A dedicated service account with only the GA properties and roles it needs.
-- Workload Identity Federation, which avoids a long-lived JSON key.
-- An explicitly injected Google credentials object when using the Ruby API.
+```ruby
+service_account = AnalyticsOps::ServiceAccount.new(
+  "/secure/path/service-account.json"
+)
 
-Cloud IAM permission alone does not grant access to a GA4 property. Add the
-service-account identity—such as
-`ga-reader@example-project.iam.gserviceaccount.com`—to the property with the
-appropriate Google Analytics role.
+workspace = AnalyticsOps::Workspace.load(
+  "config/analytics_ops.yml",
+  profile: "production",
+  service_account: service_account
+)
+```
+
+Loading the identity reads and validates the local key. It does not contact
+Google. Network access starts only when a connection or workspace operation is
+called.
 
 ## Values that are easy to confuse
 
 | Value | Example | Meaning |
 | --- | --- | --- |
-| Property ID | `123456789` | Numeric GA4 property identifier used by Admin and Data APIs |
-| Stream ID | `987654321` | Numeric data-stream resource identifier |
-| Measurement ID | `G-EXAMPLE1` | Web tagging identifier; not accepted as `property_id` or `stream_id` |
-| Account ID | `100000001` | Numeric Analytics account identifier shown by discovery |
-| OAuth client | Client ID and secret in your Cloud project | Starts a user OAuth flow; never put it in Analytics Ops YAML |
-| Service account | An IAM email identity | Receives GA property access; a JSON private key is credential material |
+| GA4 account ID | `100000001` | Analytics container shown by discovery |
+| GA4 property ID | `123456789` | Numeric reporting and configuration boundary |
+| Stream ID | `987654321` | Numeric data-stream resource |
+| Measurement ID | `G-EXAMPLE1` | Browser tagging ID; not a property or stream ID |
+| Cloud project | `example-analytics-project` | Owns APIs, quota, and the service account |
+| Service-account email | `analytics-ops@example-project.iam.gserviceaccount.com` | Identity added to GA4 Access Management |
+| Service-account JSON | A downloaded private key file | Secret used by Analytics Ops; never commit it |
 
-## Credential rules
+An API key identifies a Cloud project but cannot authorize access to private
+GA4 data or settings.
 
-- Never put credentials, paths to credentials, access tokens, refresh tokens,
-  private keys, API keys, or OAuth secrets in `analytics_ops.yml`.
-- Never put credentials in a saved plan.
-- Never commit service-account JSON.
-- Never paste credentials into an issue, fixture, log, or report.
-- Revoke or rotate credentials immediately after suspected exposure.
-- Do not create a shared public OAuth client for this gem.
+## Credential rules
 
-Analytics Ops redacts common credential patterns from translated errors, but
-redaction is a final safety net—not a safe way to handle secrets.
+- Never place the JSON key or its path in `analytics_ops.yml`.
+- Never commit a service-account key.
+- Never paste key contents into chat, issues, logs, screenshots, or reports.
+- Never place production mutation credentials in a Rails web container.
+- Revoke and replace a key immediately if it may have been exposed.
+- Remove stale keys from the service account after rotation.
 
-Official Google setup references:
+Official Google references:
 
 - [Admin API quickstart](https://developers.google.com/analytics/devguides/config/admin/v1/quickstart)
-- [Data API quickstart](https://developers.google.com/analytics/devguides/reporting/data/v1/quickstart-client-libraries)
+- [Data API quickstart](https://developers.google.com/analytics/devguides/reporting/data/v1/quickstart)

data/docs/commands.md

@@ -1,7 +1,8 @@
 # Commands
 
-The executable is `analytics-ops`. All commands use
+The executable is `analytics-ops`. Commands that operate on one property use
 `config/analytics_ops.yml` and the `production` profile unless overridden.
+`setup`, `properties`, and `discover` work before that file exists.
 
 ```text
 analytics-ops COMMAND [options]
@@ -10,22 +11,70 @@ analytics-ops COMMAND [options]
 ## Fast examples
 
 ```bash
+analytics-ops setup --service-account /absolute/path/to/service-account.json
+analytics-ops overview
+analytics-ops properties
 analytics-ops doctor
-analytics-ops audit --format json
+analytics-ops audit --json
 analytics-ops plan --output tmp/ga4-plan.json
 analytics-ops apply tmp/ga4-plan.json
-analytics-ops report landing_pages --format csv
-analytics-ops realtime --format json
+analytics-ops report landing-pages --csv
+analytics-ops realtime --json
 ```
 
 Only `apply` can write to Google.
 
-## Read-only commands
+## Setup
+
+```bash
+analytics-ops setup --service-account /absolute/path/to/service-account.json
+```
+
+Analytics Ops supports only service-account authentication. On the first run,
+pass the downloaded JSON key explicitly. Setup then:
+
+1. Validates that the file is a Google service-account key.
+2. Lists accessible accounts and properties without loading YAML.
+3. Prompts with numbered choices showing account, property name, and ID.
+4. Proves Admin and Data API read access.
+5. Creates the smallest valid `config/analytics_ops.yml` using the
+   `production` profile.
+6. Stores only the key's absolute path in
+   `~/.config/analytics_ops/connection.json` with mode `0600`.
+7. Prints `analytics-ops overview` as the next command.
+
+Setup never overwrites an existing profile that targets another property. A
+matching file is a successful no-op. The key is never copied into a project or
+printed.
+
+Later setup runs use the remembered path:
+
+```bash
+analytics-ops setup
+```
+
+Automation uses the same single route with an explicit property:
+
+```bash
+analytics-ops setup \
+  --service-account /secure/path/service-account.json \
+  --property 123456789 \
+  --non-interactive \
+  --json
+```
+
+The CLI never consults `gcloud`, browser login, Application Default
+Credentials, `GOOGLE_APPLICATION_CREDENTIALS`, or API keys.
+
+## Commands that do not change GA4
 
 | Command | Result |
 | --- | --- |
+| `setup` | Loads the service account, selects a property, verifies both APIs, and writes local configuration; never changes Google Analytics |
+| `properties` | Lists accessible account and property summaries without configuration or per-property stream calls |
 | `doctor` | Checks the local file, credentials, Admin API, Data API, property access, client versions, edit visibility, and clock |
-| `discover` | Lists accessible account IDs, property IDs, and stream IDs |
+| `discover` | Lists accessible account IDs, property IDs, and stream IDs without configuration |
+| `overview` | Returns five bounded reports for the previous 28 complete days in one batch request |
 | `snapshot` | Prints normalized managed remote state and its fingerprint |
 | `audit` | Compares desired state with a fresh snapshot; exits 2 for drift |
 | `plan` | Generates the same comparison; `--output FILE` saves its exact JSON |
@@ -34,9 +83,8 @@ Only `apply` can write to Google.
 | `realtime [NAME]` | Runs `realtime_events` by default |
 | `schema` | Prints the version-1 configuration schema |
 
-`doctor` cannot reliably inspect scopes inside an issued Google token. It
-reports that check as unknown and proves effective access with real read-only
-calls instead.
+`doctor` uses the read-only Analytics scope and proves effective access with
+small real calls to both APIs.
 
 ## Apply
 
@@ -69,23 +117,28 @@ plans and applies in one step.
 | `-c, --config PATH` | Configuration file |
 | `-p, --profile NAME` | Profile inside the file |
 | `-f, --format FORMAT` | `human`, `json`, or report-only `csv` |
+| `--json` | Shortcut for `--format json` |
+| `--csv` | Shortcut for `--format csv` |
 | `-o, --output PATH` | Save generated JSON; valid only with `plan` |
+| `--property ID` | Select an accessible property without prompting; setup only |
+| `--service-account PATH` | Connect a Google service-account JSON key; setup only |
 | `--transport grpc|rest` | Official Google-client transport |
-| `--timeout SECONDS` | Positive API call timeout |
+| `--timeout SECONDS` | Finite positive API call timeout |
 | `--log-level LEVEL` | Structured request metadata: `debug`, `info`, `warn`, or `error`; default `warn` |
 | `--yes` | Approve every operation in a saved plan; apply only |
-| `--non-interactive` | Never prompt; apply only and requires `--yes` |
+| `--non-interactive` | Never prompt; apply requires `--yes`, setup requires `--property` |
 
-Unknown arguments and options fail instead of being ignored. CSV is rejected
-for anything except report results. CSV cells beginning with spreadsheet
-formula characters are prefixed safely.
+Unknown arguments, conflicting format flags, and non-finite timeouts fail
+instead of being ignored. CSV is rejected for anything except report results.
+CSV cells whose first meaningful character is a spreadsheet formula marker
+are prefixed safely, including cells hidden behind whitespace or controls.
 
 ## Output
 
-- Human output is readable in a terminal.
+- Human output removes terminal control characters from remote text.
 - JSON output uses stable gem-owned fields and structured errors.
-- CSV contains report headers and rows only; it never applies to plans,
-  snapshots, or errors.
+- CSV contains one report's headers and rows only; it is rejected for batched
+  overviews, plans, snapshots, and errors.
 
 No command prints credentials or generated Google protobuf objects. Report
 rows are emitted only because the user requested a report; they are never
@@ -107,6 +160,7 @@ logged automatically.
 | 78 | Unsupported installed-client capability |
 | 79 | Stale saved plan |
 | 80 | Partial apply; inspect reconciliation output |
+| 130 | Interrupted by the user; no Ruby backtrace is printed |
 
 When `--format json` is selected, errors are JSON on standard error and are
 suitable for automation.

data/docs/configuration-schema-v1.json

@@ -80,13 +80,16 @@
       "required": ["event_data", "user_data", "reset_on_new_activity"],
       "properties": {
         "event_data": { "$ref": "#/$defs/retentionValue" },
-        "user_data": { "$ref": "#/$defs/retentionValue" },
+        "user_data": { "$ref": "#/$defs/userRetentionValue" },
         "reset_on_new_activity": { "type": "boolean" }
       }
     },
     "retentionValue": {
       "enum": ["2_months", "14_months", "26_months", "38_months", "50_months"]
     },
+    "userRetentionValue": {
+      "enum": ["2_months", "14_months"]
+    },
     "googleSignals": {
       "type": "object",
       "additionalProperties": false,
@@ -102,11 +105,32 @@
       "required": ["parameter_name", "display_name", "scope"],
       "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 },
+        "display_name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_ ]{0,81}$" },
+        "description": {
+          "type": "string",
+          "maxLength": 150,
+          "pattern": "^[^\\u0000-\\u001F\\u007F]*$"
+        },
         "scope": { "enum": ["event", "user", "item"] },
         "disallow_ads_personalization": { "type": "boolean" }
-      }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "scope": { "const": "user" } } },
+          "then": {
+            "properties": {
+              "parameter_name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,23}$" }
+            }
+          }
+        },
+        {
+          "if": {
+            "required": ["disallow_ads_personalization"],
+            "properties": { "disallow_ads_personalization": { "const": true } }
+          },
+          "then": { "properties": { "scope": { "const": "user" } } }
+        }
+      ]
     },
     "customMetric": {
       "type": "object",
@@ -114,16 +138,38 @@
       "required": ["parameter_name", "display_name", "scope"],
       "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 },
+        "display_name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_ ]{0,81}$" },
+        "description": {
+          "type": "string",
+          "maxLength": 150,
+          "pattern": "^[^\\u0000-\\u001F\\u007F]*$"
+        },
         "scope": { "const": "event" },
         "measurement_unit": {
           "enum": [
             "standard", "currency", "feet", "meters", "kilometers", "miles",
             "milliseconds", "seconds", "minutes", "hours"
           ]
+        },
+        "restricted_metric_types": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "enum": ["cost_data", "revenue_data"] }
         }
-      }
+      },
+      "allOf": [
+        {
+          "if": {
+            "required": ["measurement_unit"],
+            "properties": { "measurement_unit": { "const": "currency" } }
+          },
+          "then": {
+            "required": ["restricted_metric_types"],
+            "properties": { "restricted_metric_types": { "minItems": 1 } }
+          },
+          "else": { "properties": { "restricted_metric_types": { "maxItems": 0 } } }
+        }
+      ]
     }
   }
 }

data/docs/configuration.md

@@ -3,6 +3,17 @@
 Analytics Ops reads strict, versioned YAML. The file describes desired GA4
 state; it never contains credentials.
 
+For the normal first run, let setup create the file after you choose a
+property:
+
+```bash
+analytics-ops setup --service-account /absolute/path/to/service-account.json
+```
+
+Setup writes only a quoted property ID under the `production` profile. It
+will reuse a matching file but will not overwrite an existing profile that
+targets another property.
+
 ## Smallest valid file
 
 ```yaml
@@ -44,7 +55,7 @@ profiles:
         default_uri: "https://www.example.test"
 
         # Accepted only as an explicit experimental declaration.
-        # Version 0.1.0 reports a finding and does not apply this setting.
+        # Version 0.2.0 reports a finding and does not apply this setting.
         enhanced_measurement:
           enabled: true
           experimental: true
@@ -75,13 +86,16 @@ profiles:
         description: Non-sensitive calculated estimate
         scope: event
         measurement_unit: currency
+        # Google requires currency metrics to be classified explicitly.
+        restricted_metric_types:
+          - revenue_data
 
     # Checklist findings only; Analytics Ops does not claim to manage these.
     manual_requirements:
       - email_redaction_enabled
       - consent_mode_reviewed
 
-    # Explicit declaration only in 0.1.0; never silently applied.
+    # Explicit declaration only in 0.2.0; never silently applied.
     google_signals:
       state: disabled
       experimental: true
@@ -102,12 +116,13 @@ All three fields are required when `retention` is present:
 
 - `event_data`: `2_months`, `14_months`, `26_months`, `38_months`, or
   `50_months`
-- `user_data`: the same values
+- `user_data`: `2_months` or `14_months`
 - `reset_on_new_activity`: `true` or `false`
 
-Google may restrict longer periods by property type or account capabilities.
-An API rejection is returned as a typed error; Analytics Ops does not silently
-substitute a different period.
+The 26-, 38-, and 50-month event periods are available only to Analytics 360
+properties. Google does not allow those periods for user data, so Analytics
+Ops rejects them locally. An API rejection for an ineligible event period is
+returned as a typed error; the gem never substitutes a different period.
 
 ### Key events
 
@@ -119,6 +134,8 @@ substitute a different period.
 Required fields are `parameter_name`, `display_name`, and `scope`.
 Supported scopes are `event`, `user`, and `item`.
 `disallow_ads_personalization` is valid only for user-scoped dimensions.
+Display names must start with a letter and contain only letters, numbers,
+spaces, and underscores, matching Google's create/update contract.
 
 Identity is `scope + parameter_name`; display name and description are
 mutable. Immutable conflicts are findings, not automatic replacement.
@@ -131,8 +148,14 @@ Required fields are `parameter_name`, `display_name`, and
 `standard`, `currency`, `feet`, `meters`, `kilometers`, `miles`,
 `milliseconds`, `seconds`, `minutes`, and `hours`.
 
-Identity is `parameter_name`. Scope and unit are immutable; Analytics Ops
-will not archive and recreate a conflicting metric.
+A `currency` metric also requires `restricted_metric_types` containing
+`cost_data`, `revenue_data`, or both. This classification controls restricted
+data access in Google Analytics, so Analytics Ops never guesses it. The field
+must be omitted or empty for non-currency metrics.
+
+Identity is `parameter_name`. Scope, unit, and restricted-data classification
+are treated as immutable; Analytics Ops will not archive and recreate a
+conflicting metric.
 
 ## Environment variables
 
@@ -151,8 +174,9 @@ execution, YAML alias support, or Ruby-object deserialization.
 ## Strict safety rules
 
 - The file is limited to 1 MiB.
+- YAML nesting is bounded and duplicate mapping keys are rejected.
 - Unknown fields fail closed.
-- Secret-shaped fields fail closed at any depth.
+- Secret-shaped fields and credential-shaped values fail closed.
 - Numeric identifiers must be YAML strings.
 - User-visible strings reject control characters.
 - Duplicate resource identities fail validation.

data/docs/google-client-compatibility.md

@@ -9,6 +9,7 @@ second HTTP stack and does not expose generated Google objects publicly.
 | --- | --- | --- |
 | `google-analytics-admin` | `~> 0.8.0` | 0.8.0 |
 | `google-analytics-data` | `~> 0.9.0` | 0.9.0 |
+| `googleauth` | `~> 1.12` | 1.17.1 |
 
 The reviewed lockfile resolves these generated transports:
 
@@ -22,10 +23,10 @@ transport name does not make every feature Alpha: Google publishes feature
 maturity separately. Analytics Ops treats capabilities Google identifies as
 Alpha as experimental or unsupported.
 
-The pessimistic direct bounds allow reviewed patch updates inside each minor
-line and reject a new minor contract automatically. `doctor` reports the
-installed direct versions, expected bounds, and selected `grpc` or `rest`
-transport.
+The API-wrapper bounds allow reviewed patch updates inside each minor line and
+reject a new minor contract automatically. The `googleauth` bound stays within
+its compatible 1.x public API. `doctor` reports the installed Admin and Data
+wrapper versions, expected bounds, and selected `grpc` or `rest` transport.
 
 ## Executable contract coverage
 
@@ -40,11 +41,14 @@ protobuf classes for:
 - `list_key_events` and `create_key_event`
 - list/create/update custom dimensions
 - list/create/update custom metrics
+- custom-metric restricted cost/revenue enum translation
 - update web data-stream default URI
-- `run_report` and `run_realtime_report`
+- `run_report`, `batch_run_reports`, and `run_realtime_report`
 
 The tests also prove enum mappings and normalization into immutable gem-owned
-values without making network requests.
+values without making network requests. Service-account tests exercise the
+official `Google::Auth::ServiceAccountCredentials` loader with generated fake
+keys and verify the exact read/edit scopes.
 
 ## Updating a Google client