Metadata-Version: 2.4
Name: gtm-telemetry-wizard
Version: 0.1.2
Summary: Standalone GTM container IaC compiler, Playwright live verifier, GA4 telemetry ingest warmer, and guided setup wizard.
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: playwright>=1.40.0
Requires-Dist: verkit>=0.2.1

# gtm-telemetry-wizard

> Declarative GTM Container IaC Compiler, Playwright E2E Live Verifier, and GA4 Telemetry Ingestion Setup Wizard.

`gtm-telemetry-wizard` is a standalone CLI tool and Python library for automating Google Tag Manager (GTM) container setups, compiling declarative IaC specs, verifying live webpage telemetry with Playwright, and warming up GA4 measurement streams to achieve **Container Quality: Excellent**.

---

## Features

- **5-Phase Setup Wizard**: Diagnostic check, container spec compilation, live Playwright verification, GA4 ingest warm-up, and container quality reporting.
- **GA4 Ingest Warm-Up**: Delivers initial telemetry pings directly to GA4 (`/g/collect`), automatically clearing 48-hour missing traffic quality alerts.
- **Playwright E2E Verification**: Headless/Headful browser verification inspecting `gtm.js` snippet loading, `dataLayer` events, and UTM parameters.
- **Dual Deployment Options**: Automated browser import (via Playwright CDP persistent Chrome profile) or GTM REST API v2 deployment.
- **Borderless Terminal UI**: Clean Rich-powered terminal interface.

---

## Installation

```bash
uv tool install gtm-telemetry-wizard
```

Or install from source:

```bash
git clone https://github.com/bizkite-co/gtm-telemetry-wizard.git
cd gtm-telemetry-wizard
uv sync
```

`uv sync` installs this checkout as an editable development package. The
repository's `mise.toml` adds `.venv/bin` to `PATH` only while working in this
directory, so `gtw` uses the local checkout here and the PyPI installation
everywhere else.

Use `mise run check` to verify the CLI, `mise run build` to build distributions,
and `mise run release` to create and push the next patch release with `verkit`.

---

## Quick Start

### 1. Guided Setup Wizard
Run the 5-phase setup wizard for any website and container ID:

```bash
gtw wizard --domain example.com --container-id GTM-XXXXXXX --ga4-id G-YYYYYYYY
```

### 2. Using `telemetry.toml` Configuration File
Create a `telemetry.toml` in your project directory:

```toml
[site]
domain = "example.com"
container_id = "GTM-53F6J2WX"
ga4_measurement_id = "G-HJJ9TK2TKY"

[deployment]
mode = "browser"
headful = true
```

Then run:

```bash
gtw wizard --config telemetry.toml
```

---

## Python API Usage

```python
from gtm_telemetry_wizard import TelemetryConfig, TelemetryProvider

# Initialize provider
config = TelemetryConfig(domain="example.com", container_id="GTM-XXXXXXX")
provider = TelemetryProvider(config)

# Run live telemetry verification
results = provider.verify_live_telemetry()
print("GTM Loaded:", results["gtm_script_loaded"])

# Send initial GA4 warm-up ping
ping_res = provider.ping_ga4_measurement_id("G-YYYYYYYY")
print("Ping Status:", ping_res["status"])
```

---

## CLI Reference

- `gtw wizard` - Guided 5-phase telemetry setup wizard.
- `gtw sync` - Compile GTM container IaC spec.
- `gtw verify` - Run Playwright E2E live URL verification.
- `gtw ping` - Deliver initial GA4 warm-up measurement hit.

---

## License

MIT License © 2026 Bizkite Co.
