@mahe_pkm/buzl-capi 0.1.2 โ 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/Buzl_GoogleAppsScript_Template.gs +948 -948
- package/CHANGELOG.md +109 -83
- package/LICENSE +21 -21
- package/README.md +339 -253
- package/USER_HANDBOOK.html +808 -0
- package/USER_HANDBOOK.md +842 -0
- package/assets/js/buzl-tracking.js +390 -390
- package/bin/cli.js +175 -155
- package/package.json +3 -1
- package/src/cli/terminal.js +388 -388
- package/src/core/injector.js +321 -321
- package/src/core/rollback.js +281 -281
- package/src/core/scanner.js +506 -506
- package/src/core/tester.js +666 -357
- package/src/gui/public/app.js +915 -87
- package/src/gui/public/index.html +620 -230
- package/src/gui/public/style.css +1603 -509
- package/src/gui/server.js +242 -232
- package/src/index.js +47 -47
- package/src/templates/GoogleAppsScript.gs +948 -948
- package/src/templates/buzl-tracking.js +475 -475
- package/src/templates/gtm-meta-snippets.js +149 -149
package/README.md
CHANGED
|
@@ -1,253 +1,339 @@
|
|
|
1
|
-
# โก Buzl Tracker & Conversions API (
|
|
2
|
-
|
|
3
|
-
[](https://nodejs.org)
|
|
5
|
-
[](LICENSE)
|
|
6
|
-
[](package.json)
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
-
|
|
17
|
-
-
|
|
18
|
-
-
|
|
19
|
-
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
---
|
|
25
|
-
|
|
26
|
-
##
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
โ
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
npx buzl-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
npx buzl-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
```
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
-
|
|
193
|
-
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
1
|
+
# โก Buzl Tracker & Conversions API (`@mahe_pkm/buzl-capi`)
|
|
2
|
+
|
|
3
|
+
[](https://github.com/mahe-pkm/Buzl_CAPI)
|
|
4
|
+
[](https://nodejs.org)
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
[](tests/)
|
|
7
|
+
[](package.json)
|
|
8
|
+
[-orange.svg)](USER_HANDBOOK.md)
|
|
9
|
+
|
|
10
|
+
> **All-in-one Node.js CLI & Local Web GUI for automated Google Tag Manager (GTM), Meta Pixel & Conversions API (CAPI), Google Sheets CRM Multi-Tab Sync, and Zoho CRM injection with self-testing and automated PDF audit reporting.**
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## ๐ Official User Handbook & Multi-OS Commands
|
|
15
|
+
|
|
16
|
+
Looking for copy-ready command blocks for **Windows (PowerShell & CMD)**, **macOS**, and **Linux**?
|
|
17
|
+
- ๐ Read the full markdown guide: [**USER_HANDBOOK.md**](USER_HANDBOOK.md)
|
|
18
|
+
- ๐จ๏ธ Open and print or save the handbook as a PDF: [**USER_HANDBOOK.html**](USER_HANDBOOK.html)
|
|
19
|
+
- ๐ Or run directly from terminal:
|
|
20
|
+
```bash
|
|
21
|
+
npx @mahe_pkm/buzl-capi --handbook
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## ๐ฏ The Problem This Solves
|
|
27
|
+
|
|
28
|
+
When deploying or optimizing lead-generation landing pages, configuring analytics tags, conversion pixels, CRM webhooks, and spreadsheet logging requires tedious manual labor:
|
|
29
|
+
- Editing `<head>` and `<body>` tags across dozens of HTML files.
|
|
30
|
+
- Writing custom JavaScript form interceptors.
|
|
31
|
+
- Manually capturing UTM parameters, Google Click IDs (`gclid`), and Meta Click IDs (`fbclid`, `_fbc`, `_fbp`).
|
|
32
|
+
- Paying expensive monthly subscription fees for third-party webhook connectors (e.g. Zapier, Make).
|
|
33
|
+
- Fixing broken formulas in spreadsheets when rows insert at the top.
|
|
34
|
+
|
|
35
|
+
**`buzl-tracker` completely automates this entire pipeline in under 60 seconds.**
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## ๐๏ธ Multi-Channel Lead Flow Architecture
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
43
|
+
โ Website Visitor Submits โ
|
|
44
|
+
โ HTML Form or WhatsApp โ
|
|
45
|
+
โโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโ
|
|
46
|
+
โ
|
|
47
|
+
โผ
|
|
48
|
+
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
49
|
+
โ buzl-tracking.js โ
|
|
50
|
+
โ Runtime Client Interceptor โ
|
|
51
|
+
โ - Captures UTMs & Cookies โ
|
|
52
|
+
โ - Generates Unique leadId โ
|
|
53
|
+
โโโโโโโโฌโโโโโโโโฌโโโโโโโโฌโโโโโโโโ
|
|
54
|
+
โ โ โ
|
|
55
|
+
โโโโโโโโโโโโโโโโโโ โ โโโโโโโโโโโโโโโโโโ
|
|
56
|
+
โผ โผ โผ
|
|
57
|
+
โโโโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
58
|
+
โ Google Tag Manager(GTM) โ โ Meta Pixel & CAPI โ โ Google Sheets Lead CRM โ
|
|
59
|
+
โ - dataLayer event โ โ - fbq 'Lead' โ โ - Direct Apps Script โ
|
|
60
|
+
โ - Deferred / Instant โ โ - event_id dedup โ โ - Top row lead insert โ
|
|
61
|
+
โโโโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโ โ - Forward Layout CRM โ
|
|
62
|
+
โ - Auto-Filtered Subtabs โ
|
|
63
|
+
โ - Pruned Rep Tabs โ
|
|
64
|
+
โโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
---
|
|
68
|
+
|
|
69
|
+
## ๐ Quick Start by Operating System
|
|
70
|
+
|
|
71
|
+
Run inside your landing page project folder (or pass directory path as an argument):
|
|
72
|
+
|
|
73
|
+
### ๐ช Windows (PowerShell)
|
|
74
|
+
```powershell
|
|
75
|
+
# Interactive Terminal Setup
|
|
76
|
+
npx @mahe_pkm/buzl-capi
|
|
77
|
+
|
|
78
|
+
# Local Web GUI Dashboard (port 3333)
|
|
79
|
+
npx @mahe_pkm/buzl-capi --gui
|
|
80
|
+
|
|
81
|
+
# Create Snapshot Backup
|
|
82
|
+
npx @mahe_pkm/buzl-capi --backup "Pre-Launch Baseline"
|
|
83
|
+
|
|
84
|
+
# Rollback to Previous Snapshot
|
|
85
|
+
npx @mahe_pkm/buzl-capi --restore
|
|
86
|
+
|
|
87
|
+
# Clean Uninstallation of All Tracking
|
|
88
|
+
npx @mahe_pkm/buzl-capi --uninstall
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### ๐ macOS (Terminal / zsh)
|
|
92
|
+
```bash
|
|
93
|
+
# Interactive Terminal Setup
|
|
94
|
+
npx @mahe_pkm/buzl-capi
|
|
95
|
+
|
|
96
|
+
# Local Web GUI Dashboard (port 3333)
|
|
97
|
+
npx @mahe_pkm/buzl-capi --gui
|
|
98
|
+
|
|
99
|
+
# Create Snapshot Backup
|
|
100
|
+
npx @mahe_pkm/buzl-capi --backup "Pre-Launch Baseline"
|
|
101
|
+
|
|
102
|
+
# Rollback to Previous Snapshot
|
|
103
|
+
npx @mahe_pkm/buzl-capi --restore
|
|
104
|
+
|
|
105
|
+
# Clean Uninstallation of All Tracking
|
|
106
|
+
npx @mahe_pkm/buzl-capi --uninstall
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
### ๐ง Linux (bash / sh)
|
|
110
|
+
```bash
|
|
111
|
+
# Interactive Terminal Setup
|
|
112
|
+
npx @mahe_pkm/buzl-capi
|
|
113
|
+
|
|
114
|
+
# Local Web GUI Dashboard (port 3333)
|
|
115
|
+
npx @mahe_pkm/buzl-capi --gui
|
|
116
|
+
|
|
117
|
+
# Create Snapshot Backup
|
|
118
|
+
npx @mahe_pkm/buzl-capi --backup "Pre-Launch Baseline"
|
|
119
|
+
|
|
120
|
+
# Rollback to Previous Snapshot
|
|
121
|
+
npx @mahe_pkm/buzl-capi --restore
|
|
122
|
+
|
|
123
|
+
# Clean Uninstallation of All Tracking
|
|
124
|
+
npx @mahe_pkm/buzl-capi --uninstall
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
---
|
|
128
|
+
|
|
129
|
+
## ๐ฆ NPM Package Installation, Updating & Version Management
|
|
130
|
+
|
|
131
|
+
### 1. Always Run Latest via NPX (Bypasses Local Cache)
|
|
132
|
+
Because `npx` caches previously downloaded packages locally, always specify `@latest` to ensure you execute the newest release:
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
# Always fetch and run the newest release
|
|
136
|
+
npx @mahe_pkm/buzl-capi@latest
|
|
137
|
+
|
|
138
|
+
# Launch Web GUI with latest release
|
|
139
|
+
npx @mahe_pkm/buzl-capi@latest --gui
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
### 2. Global CLI Installation & Updating
|
|
143
|
+
Install globally to execute `buzl-tracker` or `buzl-capi` anywhere without `npx`:
|
|
144
|
+
|
|
145
|
+
```bash
|
|
146
|
+
# Install globally (or upgrade existing global installation to latest)
|
|
147
|
+
npm install -g @mahe_pkm/buzl-capi@latest
|
|
148
|
+
|
|
149
|
+
# Alternative: update existing global package
|
|
150
|
+
npm update -g @mahe_pkm/buzl-capi
|
|
151
|
+
|
|
152
|
+
# Verify installed version
|
|
153
|
+
buzl-tracker --help
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
### 3. Updating as a Local Project Dependency
|
|
157
|
+
If installed inside a local project directory:
|
|
158
|
+
|
|
159
|
+
```bash
|
|
160
|
+
# Check if a newer version is available
|
|
161
|
+
npm outdated @mahe_pkm/buzl-capi
|
|
162
|
+
|
|
163
|
+
# Update to latest version in package.json
|
|
164
|
+
npm install @mahe_pkm/buzl-capi@latest
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
### 4. Author Publishing & Release Workflow (with 2FA / OTP)
|
|
168
|
+
For maintainers publishing updates to npm with Two-Factor Authentication (2FA) active:
|
|
169
|
+
|
|
170
|
+
```bash
|
|
171
|
+
# 1. Bump version
|
|
172
|
+
npm version patch
|
|
173
|
+
|
|
174
|
+
# 2. Push tags and commits to GitHub
|
|
175
|
+
git push origin main --tags
|
|
176
|
+
|
|
177
|
+
# 3. Publish to npm registry with 2FA authenticator OTP code & explicit latest tag
|
|
178
|
+
npm publish --tag latest --otp=YOUR_6_DIGIT_OTP
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
> **Note on `--tag latest`:**
|
|
182
|
+
> When publishing a patch/minor release where earlier versions (e.g. `1.0.1`) were previously registered on npm, npm blocks lower semver numbers from automatically updating the `latest` pointer. Specifying `--tag latest` is required so `npx @mahe_pkm/buzl-capi` and `npm install` immediately resolve to the new release.
|
|
183
|
+
|
|
184
|
+
---
|
|
185
|
+
|
|
186
|
+
## โก CLI Command Reference
|
|
187
|
+
|
|
188
|
+
| Command / Flag | Alias | Description |
|
|
189
|
+
|---|---|---|
|
|
190
|
+
| `npx @mahe_pkm/buzl-capi [dir]` | `npx buzl-tracker` | Launches the step-by-step interactive terminal wizard. |
|
|
191
|
+
| `npx @mahe_pkm/buzl-capi --gui` | `-g` | Launches local Web GUI dashboard on port 3333. |
|
|
192
|
+
| `npx @mahe_pkm/buzl-capi --backup [name]` | `-b` | Creates a point-in-time snapshot backup of all HTML files. |
|
|
193
|
+
| `npx @mahe_pkm/buzl-capi --list-backups` | โ | Lists all saved snapshot backups on disk. |
|
|
194
|
+
| `npx @mahe_pkm/buzl-capi --restore [name]` | `-r`, `--rollback` | Reverts all HTML files to the named snapshot (or latest). |
|
|
195
|
+
| `npx @mahe_pkm/buzl-capi --uninstall` | `-u` | Cleanly strips GTM, Meta Pixel, runtime scripts, and form hooks. |
|
|
196
|
+
| `npx @mahe_pkm/buzl-capi --handbook` | โ | Opens the printable User Handbook in your default browser. |
|
|
197
|
+
| `npx @mahe_pkm/buzl-capi --help` | `-h` | Displays the help manual and CLI options. |
|
|
198
|
+
|
|
199
|
+
---
|
|
200
|
+
|
|
201
|
+
## ๐ Google Sheets Multi-Tab CRM Engine (`GoogleAppsScript.gs`)
|
|
202
|
+
|
|
203
|
+
`buzl-tracker` comes with an enterprise-grade Google Apps Script CRM engine that turns any Google Sheet into an automated lead dashboard with **zero monthly subscription fees**:
|
|
204
|
+
|
|
205
|
+
### ๐ Key CRM Features:
|
|
206
|
+
1. **Forward Operational Layout**:
|
|
207
|
+
`Handled By` (Col F) and `Comments` (Col G) sit directly adjacent to `Lead Stage` (Col E) for rapid qualification:
|
|
208
|
+
```
|
|
209
|
+
| Name | Location | Phone | Email | Lead Stage | Handled By | Comments | Is Qualified | ...
|
|
210
|
+
```
|
|
211
|
+
2. **Top Row Insertion (Row 2)**:
|
|
212
|
+
Incoming web leads insert directly at **Row 2** (top of sheet) immediately below the header.
|
|
213
|
+
3. **Shift-Proof Sub-Tabs**:
|
|
214
|
+
Status tabs (`New`, `Contacted`, `Qualified`, `Converted`, `Spam`, `Test`) use `=FILTER(INDIRECT(...))` formulas that **never break (#REF!)** when new leads push rows down.
|
|
215
|
+
4. **Full-Row Highlighting Across Columns A:Z**:
|
|
216
|
+
Rows automatically light up with clean, professional status colors when `Lead Stage` is updated.
|
|
217
|
+
5. **Dynamic Team Member Tabs & Auto-Pruning**:
|
|
218
|
+
- Each team member assigned a lead gets an individual tab named after them.
|
|
219
|
+
- Team member tabs are strictly positioned at the very end of the sheet bar.
|
|
220
|
+
- If a team member has 0 leads assigned, their tab is **automatically deleted**.
|
|
221
|
+
6. **Full-Column Dropdown Validations (Rows 2 to 1000)**:
|
|
222
|
+
- `Lead Stage`: `['New', 'Contacted', 'Qualified', 'Converted', 'Spam', 'Test']`
|
|
223
|
+
- `Handled By`: Dynamic dropdown populated from `DEFAULT_TEAM_MEMBERS` + active assigned reps.
|
|
224
|
+
- `Is Qualified` & `Is Spam`: `['No', 'Yes']`
|
|
225
|
+
7. **Official Buzl Navy Blue Header**:
|
|
226
|
+
Header styled in `#1E4E9E` with bold white text (`#FFFFFF`) at 32px height (> 8.5:1 WCAG contrast).
|
|
227
|
+
8. **Global 12-Hour Timestamps**:
|
|
228
|
+
Timestamps formatted as `dd-MMM-yyyy hh:mm a` (dynamic spreadsheet timezone).
|
|
229
|
+
9. **`โก Buzl Lead CRM` Top Menu**:
|
|
230
|
+
1-click sheet management directly inside Google Sheets:
|
|
231
|
+
- `โก Initialize & Upgrade All CRM Tabs`
|
|
232
|
+
- `๐ Sort All Leads (Newest First)`
|
|
233
|
+
- `๐จ Apply Status Color Coding`
|
|
234
|
+
- `๐ฅ Sync Team Member Tabs`
|
|
235
|
+
- `๐ Apply Dropdowns & Layout to All Sheets`
|
|
236
|
+
|
|
237
|
+
### Setup in 30 Seconds:
|
|
238
|
+
1. Open your Google Sheet.
|
|
239
|
+
2. Navigate to **Extensions** > **Apps Script**.
|
|
240
|
+
3. Replace all contents with the code from `Buzl_GoogleAppsScript_Template.gs` (or copy from GUI modal).
|
|
241
|
+
4. Click **Deploy** > **New deployment** > Type: **Web app** > Execute as: **Me** > Access: **Anyone**.
|
|
242
|
+
5. Copy the generated Web App URL and paste it into `buzl-tracker`!
|
|
243
|
+
|
|
244
|
+
---
|
|
245
|
+
|
|
246
|
+
## ๐พ Unified `.buzl/snapshots/` Storage & Content Hashing
|
|
247
|
+
|
|
248
|
+
All snapshot backups are stored inside a single hidden `.buzl` directory in your website root:
|
|
249
|
+
|
|
250
|
+
```
|
|
251
|
+
Your_Website/
|
|
252
|
+
โโโ index.html
|
|
253
|
+
โโโ assets/
|
|
254
|
+
โโโ .buzl/ <-- Shared with @mahe_pkm/buzl-html-editor
|
|
255
|
+
โโโ snapshots/
|
|
256
|
+
โโโ 2026-09-14T10-45-12_a8f3b9c2/ <-- Timestamp + SHA-1 Content Hash
|
|
257
|
+
โโโ backup-manifest.json <-- Full metadata & integrity hash
|
|
258
|
+
โโโ index.html <-- Exact pre-injection copy
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
- **Zero Root Clutter**: Unifies storage under `.buzl` alongside other Buzl ecosystem tools (such as `@mahe_pkm/buzl-html-editor`).
|
|
262
|
+
- **Cryptographic Content Hashing**: Computes an 8-character SHA-1 content hash across all HTML files for tamper-proof verification.
|
|
263
|
+
- **Safe Across Folder Moves**: Backups travel with the website using relative paths.
|
|
264
|
+
- **Backward Compatible**: Automatically detects and restores from legacy `.buzl-backup-*` folders if present.
|
|
265
|
+
|
|
266
|
+
---
|
|
267
|
+
|
|
268
|
+
## ๐ Multi-Page Directory Support
|
|
269
|
+
|
|
270
|
+
For multi-page websites with nested directories (e.g. `/services/sports-physio.html`, `/about/team/doctor.html`):
|
|
271
|
+
- The scanner detects all HTML files regardless of directory nesting depth.
|
|
272
|
+
- Injects proper relative script paths (`assets/js/...`, `../assets/js/...`, `../../assets/js/...`) to guarantee that tracking scripts load accurately without 404 errors.
|
|
273
|
+
|
|
274
|
+
---
|
|
275
|
+
|
|
276
|
+
## ๐ฑ Universal WhatsApp Auto-Fetch
|
|
277
|
+
|
|
278
|
+
- Automatically detects WhatsApp numbers from button `href` attributes, click actions, and phone links.
|
|
279
|
+
- Populates the site configuration automatically.
|
|
280
|
+
- Pre-fills WhatsApp message templates with submitted form data (Name, Service, Location) so inquiries hand off directly to your team's WhatsApp chat.
|
|
281
|
+
|
|
282
|
+
---
|
|
283
|
+
|
|
284
|
+
## ๐ป Programmatic Node.js SDK
|
|
285
|
+
|
|
286
|
+
`buzl-tracker` can also be used programmatically in custom Node.js build scripts:
|
|
287
|
+
|
|
288
|
+
```javascript
|
|
289
|
+
const {
|
|
290
|
+
scanProject,
|
|
291
|
+
applyInjection,
|
|
292
|
+
runVerification,
|
|
293
|
+
createBackup,
|
|
294
|
+
restoreBackup,
|
|
295
|
+
removeTracking
|
|
296
|
+
} = require('buzl-tracker');
|
|
297
|
+
|
|
298
|
+
const projectDir = './my-site';
|
|
299
|
+
|
|
300
|
+
// 1. Scan site and discover forms
|
|
301
|
+
const scan = scanProject(projectDir);
|
|
302
|
+
console.log(`Found ${scan.files.length} HTML files and ${scan.formArchetypes.length} forms`);
|
|
303
|
+
|
|
304
|
+
// 2. Inject tracking
|
|
305
|
+
const config = {
|
|
306
|
+
gtmId: 'GTM-XXXXXXX',
|
|
307
|
+
pixelId: '123456789012345',
|
|
308
|
+
sheetsUrl: 'https://script.google.com/macros/s/XXXXX/exec',
|
|
309
|
+
zohoFormId: '',
|
|
310
|
+
whatsappNumber: '+919876543210'
|
|
311
|
+
};
|
|
312
|
+
|
|
313
|
+
const result = applyInjection(projectDir, scan.files.map(f => f.filePath), config);
|
|
314
|
+
console.log(result.message);
|
|
315
|
+
|
|
316
|
+
// 3. Verify injection integrity
|
|
317
|
+
const testReport = await runVerification(projectDir, scan.files.map(f => f.filePath), config);
|
|
318
|
+
console.log('Self-Test Results:', testReport);
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
---
|
|
322
|
+
|
|
323
|
+
## ๐งช Running Tests
|
|
324
|
+
|
|
325
|
+
The test suite runs with zero external test runners using Node.js core `node:assert`:
|
|
326
|
+
```bash
|
|
327
|
+
npm test
|
|
328
|
+
```
|
|
329
|
+
Runs 37 comprehensive unit & integration tests covering:
|
|
330
|
+
- Safe AST HTML injection & tag de-duplication
|
|
331
|
+
- Multi-page relative asset resolution
|
|
332
|
+
- WhatsApp auto-discovery and button mapping
|
|
333
|
+
- Google Apps Script CRM template synchronization and validation formulas
|
|
334
|
+
|
|
335
|
+
---
|
|
336
|
+
|
|
337
|
+
## ๐ License
|
|
338
|
+
|
|
339
|
+
MIT License ยฉ 2026 Buzl Digital Solutions. See [LICENSE](LICENSE) for details.
|