gtm-type-generator 0.1.0

package/README.md

@@ -0,0 +1,116 @@
+# Google Tag Manager DataLayer Type Generator (`gtm-type-generator`)
+
+[![npm version](https://img.shields.io/npm/v/gtm-type-generator.svg)](https://www.npmjs.com/package/gtm-type-generator)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A CLI tool that automatically generates strict TypeScript definitions for your `window.dataLayer.push` method by directly fetching your configuration from the Google Tag Manager (GTM) API.
+
+## Why?
+Without strict types, `dataLayer.push` is a black box. A typo in an event name or a missing variable can silently break your tracking.
+This tool solves that by looking at your actual GTM workspace and creating types that enforce correctness at compile time.
+
+```typescript
+// With gtm-type-generator, this gives a TS error because 'method' is required for the 'login' event!
+window.dataLayer.push({ event: 'login' }); 
+
+// ✅ Correct
+window.dataLayer.push({ event: 'login', method: 'Google' });
+```
+
+## Features
+- **Type Safety**: Enforces correct `event` names and their associated variables based on your actual GTM Triggers and Tags.
+- **Auto-Sync**: Connects directly to the Tag Manager API v2 to fetch your latest container configuration.
+- **Seamless Integration**: Designed to be run as an npm script to keep your codebase in sync with your GTM workspace.
+
+## Installation
+
+```bash
+npm install -D gtm-type-generator
+```
+
+## Authentication Setup
+
+To access the GTM API, you need a Google Service Account:
+1. Go to the [Google Cloud Console](https://console.cloud.google.com/) and enable the **Tag Manager API**.
+2. Create a **Service Account** and download its JSON key file.
+3. **CRITICAL**: Go to your [Google Tag Manager Admin Panel](https://tagmanager.google.com/), select "User Management", and invite the Service Account's email address with at least **Read** permissions for the target container.
+
+## Usage
+
+### 1. Add an npm script
+Add a script to your `package.json` to easily update your types:
+
+```json
+{
+  "scripts": {
+    "update:gtm-type": "gtm-type-generator generate --account-id 123456 --container-id 987654 --workspace-id 2 --key-file ./gtm-service-account.json --output src/types/gtm.d.ts"
+  }
+}
+```
+
+*Tip: You can also use environment variables (`GTM_ACCOUNT_ID`, `GTM_CONTAINER_ID`, `GTM_WORKSPACE_ID`, `GOOGLE_APPLICATION_CREDENTIALS`) instead of passing them as CLI flags.*
+
+Run the script:
+```bash
+npm run update:gtm-type
+```
+
+### 2. Configure TypeScript (`tsconfig.json`)
+Ensure your TypeScript compiler includes the generated `.d.ts` file so it automatically extends the global `Window` interface across your project.
+
+```json
+{
+  "compilerOptions": {
+    // ... other options
+  },
+  "include": [
+    "src/**/*",
+    "src/types/gtm.d.ts" // Ensure the output path is included here
+  ]
+}
+```
+
+## Development
+
+### Prerequisites
+- Node.js 20+
+- npm
+
+### Setup
+```bash
+npm install
+```
+
+### Scripts
+- `npm run build`: Build the project using esbuild.
+- `npm test`: Run unit tests using Vitest.
+- `npm run lint`: Run ESLint to check for code style and potential errors.
+- `npm run lint -- --fix`: Automatically fix linting issues.
+
+### CI/CD
+This project uses GitHub Actions for continuous integration and delivery:
+- **CI**: Runs on every push to `main` and all Pull Requests. It executes linting, tests, and a build to ensure code quality.
+- **Release**: Automatically publishes to npm when a new tag starting with `v` (e.g., `v1.0.0`) is pushed to the repository. Note: Requires `NPM_TOKEN` to be set in GitHub Secrets.
+
+## Architecture & Extraction Process
+
+This tool generates types by analyzing the relationships between Triggers, Tags, and Variables in your GTM workspace.
+
+1. **API Client**: Authenticates and fetches Triggers, Tags, and Variables from the specified GTM workspace.
+2. **Config Extraction**:
+    - **Trigger Analysis**: Scans for "Custom Event" triggers and extracts the `event` name (e.g., `login`, `purchase`).
+    - **Variable Identification**: Finds all Tags that fire on those triggers and recursively extracts any `{{Data Layer Variable}}` references within their parameters or HTML.
+    - **Mapping**: Maps the identified variables to the corresponding `event` name.
+3. **Generator**: Outputs a union type `GtmDataLayerEvent` where each member represents a specific GTM custom event and its required/optional variables.
+
+```mermaid
+graph TD
+    API[GTM API v2] --> Triggers[Extract Custom Event Triggers]
+    Triggers --> Tags[Identify Linked Tags]
+    Tags --> Vars[Extract Data Layer Variables from Tags]
+    Vars --> Union[Map to GtmDataLayerEvent Union Member]
+    Union --> TS[Generate gtm.d.ts]
+```
+
+## License
+MIT