@walkeros/cli 0.8.0 → 1.0.1-next-1768820936934
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/CHANGELOG.md +36 -0
- package/README.md +37 -17
- package/dist/examples/README.md +33 -0
- package/dist/examples/flow-complete.json +571 -0
- package/dist/examples/flow-complete.md +247 -0
- package/dist/index.d.ts +2 -10
- package/dist/index.js +45 -44
- package/dist/index.js.map +1 -1
- package/examples/README.md +33 -0
- package/examples/flow-complete.json +571 -0
- package/examples/flow-complete.md +247 -0
- package/package.json +3 -3
- package/dist/walker.js +0 -1
|
@@ -0,0 +1,247 @@
|
|
|
1
|
+
# flow-complete.json - Comprehensive walkerOS Flow Example
|
|
2
|
+
|
|
3
|
+
This example demonstrates **ALL JSON-compatible walkerOS features** with
|
|
4
|
+
real-world patterns. It contains two named flows (`web` and `server`) showing a
|
|
5
|
+
complete event tracking architecture.
|
|
6
|
+
|
|
7
|
+
## Architecture
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
11
|
+
│ WEB FLOW │
|
|
12
|
+
│ │
|
|
13
|
+
│ Browser Source ─┐ │
|
|
14
|
+
│ DataLayer Source ──▶ [Validator] ──▶ Collector ──▶ GA4 Destination │
|
|
15
|
+
│ Demo Source ────┘ └──▶ API Destination │
|
|
16
|
+
│ │ │
|
|
17
|
+
└──────────────────────────────────────────────────────────────│──────────────┘
|
|
18
|
+
▼
|
|
19
|
+
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
20
|
+
│ SERVER FLOW │
|
|
21
|
+
│ │
|
|
22
|
+
│ HTTP Request ──▶ Express Source ──▶ Collector ──▶ [Fingerprint] ──────┐ │
|
|
23
|
+
│ │ [Validator] │ │
|
|
24
|
+
│ │ ▼ │
|
|
25
|
+
│ └── ingest: IP, user-agent ────────▶ Meta Destination
|
|
26
|
+
│ language, referer Demo Destination│
|
|
27
|
+
└─────────────────────────────────────────────────────────────────────────────┘
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## Quick Start
|
|
31
|
+
|
|
32
|
+
### Run Web Flow
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
cd walkerOS
|
|
36
|
+
npx walkeros serve packages/cli/examples/flow-complete.json --flow web
|
|
37
|
+
# Open http://localhost:3000 - demo events fire automatically
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
### Run Server Flow
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
cd walkerOS
|
|
44
|
+
npx walkeros run packages/cli/examples/flow-complete.json --flow server
|
|
45
|
+
|
|
46
|
+
# Test health
|
|
47
|
+
curl http://localhost:8080/health
|
|
48
|
+
|
|
49
|
+
# Send test event
|
|
50
|
+
curl -X POST http://localhost:8080/collect \
|
|
51
|
+
-H "Content-Type: application/json" \
|
|
52
|
+
-d '{
|
|
53
|
+
"name": "order complete",
|
|
54
|
+
"data": {"id": "ORD-999", "total": 99.99, "currency": "EUR"},
|
|
55
|
+
"user": {"email": "test@example.com", "id": "U-123"},
|
|
56
|
+
"nested": [{"entity": "product", "data": {"id": "P1", "name": "Item", "price": 99.99, "quantity": 1}}]
|
|
57
|
+
}'
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
### Run Both (Full Pipeline)
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
# Terminal 1: Start server
|
|
64
|
+
npx walkeros run packages/cli/examples/flow-complete.json --flow server
|
|
65
|
+
|
|
66
|
+
# Terminal 2: Start web (sends to server via API destination)
|
|
67
|
+
npx walkeros serve packages/cli/examples/flow-complete.json --flow web
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## Feature Inventory
|
|
73
|
+
|
|
74
|
+
### Features Used (51)
|
|
75
|
+
|
|
76
|
+
#### Mapping - Value Extraction
|
|
77
|
+
|
|
78
|
+
| Feature | Location | Example |
|
|
79
|
+
| ----------------- | ----------------- | ------------------------------------------------------------ |
|
|
80
|
+
| Key extraction | GA4 page_view | `"page_title": "data.title"` |
|
|
81
|
+
| Static value | Meta ViewContent | `"content_type": { "value": "product" }` |
|
|
82
|
+
| Key with fallback | GA4 add_to_cart | `{ "key": "data.currency", "value": "$variables.currency" }` |
|
|
83
|
+
| Nested key (deep) | dataLayer mapping | `"items.0.item_id"` |
|
|
84
|
+
|
|
85
|
+
#### Mapping - Structure
|
|
86
|
+
|
|
87
|
+
| Feature | Location | Example |
|
|
88
|
+
| --------------------- | ------------------ | ----------------------------------------------------------- |
|
|
89
|
+
| Map (object) | GA4 purchase | `"data": { "map": { ... } }` |
|
|
90
|
+
| Loop with "nested" | GA4 purchase items | `{ "loop": ["nested", { "map": {...} }] }` |
|
|
91
|
+
| Loop with "this" | GA4 add_to_cart | `{ "loop": ["this", { "map": {...} }] }` |
|
|
92
|
+
| Set (single value) | Meta ViewContent | `"content_ids": { "set": ["data.id"] }` |
|
|
93
|
+
| Set (multiple values) | Meta settings | `"external_id": { "set": ["user.device", "user.session"] }` |
|
|
94
|
+
| Direct passthrough | Meta PageView | `"data": "data"` |
|
|
95
|
+
|
|
96
|
+
#### Mapping - Control
|
|
97
|
+
|
|
98
|
+
| Feature | Location | Example |
|
|
99
|
+
| -------------------- | ------------------- | ----------------------------------------------------------- |
|
|
100
|
+
| Consent-gated field | API destination | `{ "key": "user.email", "consent": { "marketing": true } }` |
|
|
101
|
+
| Ignore rule | GA4/API test events | `{ "ignore": true }` |
|
|
102
|
+
| Wildcard action (\*) | GA4 test, Meta | `"test": { "*": { "ignore": true } }` |
|
|
103
|
+
| Wildcard entity (\*) | Meta click handler | `"*": { "click": { "name": "CustomEvent" } }` |
|
|
104
|
+
|
|
105
|
+
#### Definitions & Variables
|
|
106
|
+
|
|
107
|
+
| Feature | Location | Example |
|
|
108
|
+
| -------------------- | ------------------ | -------------------------------------------- |
|
|
109
|
+
| Root-level variables | Root | `"currency": "EUR"` |
|
|
110
|
+
| Flow-level variables | server.variables | `"metaPixelId": "${META_PIXEL_ID:...}"` |
|
|
111
|
+
| Environment variable | Variables | `"${GA4_MEASUREMENT_ID:G-DEMO123456}"` |
|
|
112
|
+
| Env with default | Variables | `"${API_URL:http://localhost:8080/collect}"` |
|
|
113
|
+
| $variables reference | GA4 settings | `"$variables.ga4MeasurementId"` |
|
|
114
|
+
| Definition (complex) | Root definitions | `"ga4ItemsLoop": { "loop": [...] }` |
|
|
115
|
+
| $ref reference | GA4 purchase items | `{ "$ref": "#/definitions/ga4ItemsLoop" }` |
|
|
116
|
+
|
|
117
|
+
#### Sources
|
|
118
|
+
|
|
119
|
+
| Feature | Location | Example |
|
|
120
|
+
| -------------------- | --------- | ------------------------------------- |
|
|
121
|
+
| Primary source | browser | `"primary": true` |
|
|
122
|
+
| Multiple sources | web flow | browser + dataLayer + demo |
|
|
123
|
+
| Source-level mapping | dataLayer | `"mapping": { "add_to_cart": {...} }` |
|
|
124
|
+
| Pre-collector chain | dataLayer | `"next": "dataLayerValidator"` |
|
|
125
|
+
| Demo source events | demo | Pre-configured test events |
|
|
126
|
+
|
|
127
|
+
#### Transformers
|
|
128
|
+
|
|
129
|
+
| Feature | Location | Example |
|
|
130
|
+
| ----------------------- | ------------------ | ---------------------------------- |
|
|
131
|
+
| Validator transformer | dataLayerValidator | JSON Schema validation |
|
|
132
|
+
| Fingerprint transformer | server | Hash context fields to `user.hash` |
|
|
133
|
+
| Transformer chaining | server | `"next": "serverValidator"` |
|
|
134
|
+
| Post-collector chain | Meta | `"before": "fingerprint"` |
|
|
135
|
+
| Contract validation | serverValidator | Entity/action schemas |
|
|
136
|
+
| Format option | serverValidator | `"format": true` |
|
|
137
|
+
|
|
138
|
+
#### Destinations
|
|
139
|
+
|
|
140
|
+
| Feature | Location | Example |
|
|
141
|
+
| --------------------- | ---------------- | ---------------------------------- |
|
|
142
|
+
| Destination consent | GA4 | `"consent": { "marketing": true }` |
|
|
143
|
+
| Destination mapping | All destinations | Entity/action to vendor events |
|
|
144
|
+
| Multiple destinations | Both flows | GA4 + API, Meta + Demo |
|
|
145
|
+
| Batch option | API | `"batch": 5` |
|
|
146
|
+
|
|
147
|
+
#### Collector
|
|
148
|
+
|
|
149
|
+
| Feature | Location | Example |
|
|
150
|
+
| ----------------- | --------------- | --------------------------------------- |
|
|
151
|
+
| Tagging | Both collectors | `"tagging": 1` |
|
|
152
|
+
| Consent defaults | Both collectors | `"consent": { "functional": true }` |
|
|
153
|
+
| Globals | Both collectors | `"environment": "demo"` |
|
|
154
|
+
| Custom properties | web collector | `"custom": { "campaign": "flow-demo" }` |
|
|
155
|
+
| User defaults | web collector | `"user": { "id": "anonymous" }` |
|
|
156
|
+
|
|
157
|
+
#### Server-Specific
|
|
158
|
+
|
|
159
|
+
| Feature | Location | Example |
|
|
160
|
+
| -------------------- | ----------- | ----------------------------------------------- |
|
|
161
|
+
| Ingest metadata | http source | `"context.ip": "ip"` |
|
|
162
|
+
| Language header | ingest | `"context.language": "headers.accept-language"` |
|
|
163
|
+
| Policy | Meta | Pre-processing field transformation |
|
|
164
|
+
| Policy consent-gated | Meta | `"user_data.em"` with consent |
|
|
165
|
+
| Policy nested map | Meta | `"custom_data.request_meta": { "map": {...} }` |
|
|
166
|
+
|
|
167
|
+
#### Browser Source
|
|
168
|
+
|
|
169
|
+
| Feature | Location | Example |
|
|
170
|
+
| --------------- | -------- | ---------------------------------- |
|
|
171
|
+
| Prefix | browser | `"prefix": "data-elb"` |
|
|
172
|
+
| Auto pageview | browser | `"pageview": true` |
|
|
173
|
+
| Session consent | browser | `"session": { "consent": {...} }` |
|
|
174
|
+
| ELB binding | browser | `"elb": "elb"`, `"elbLayer": true` |
|
|
175
|
+
|
|
176
|
+
---
|
|
177
|
+
|
|
178
|
+
### Features NOT Used (15)
|
|
179
|
+
|
|
180
|
+
#### Requires JavaScript (7)
|
|
181
|
+
|
|
182
|
+
These features cannot be used in pure JSON configurations:
|
|
183
|
+
|
|
184
|
+
| Feature | Reason |
|
|
185
|
+
| --------------------------- | ----------------------------- |
|
|
186
|
+
| `fn:` function | Requires JavaScript callback |
|
|
187
|
+
| `condition:` | Requires JavaScript predicate |
|
|
188
|
+
| Conditional mapping (array) | Requires condition functions |
|
|
189
|
+
| Custom transformer code | Requires JavaScript |
|
|
190
|
+
| Custom source code | Requires JavaScript |
|
|
191
|
+
| Custom destination code | Requires JavaScript |
|
|
192
|
+
| Event handler callbacks | Requires JavaScript |
|
|
193
|
+
|
|
194
|
+
#### Omitted for Clarity (8)
|
|
195
|
+
|
|
196
|
+
These features could be added but were omitted to keep the example focused:
|
|
197
|
+
|
|
198
|
+
| Feature | Why Omitted |
|
|
199
|
+
| ------------------------- | ----------------------------- |
|
|
200
|
+
| Multiple named flows (3+) | Two flows sufficient for demo |
|
|
201
|
+
| Queue config | Advanced batching scenario |
|
|
202
|
+
| Retry config | Advanced error handling |
|
|
203
|
+
| Custom fetch options | API destination advanced |
|
|
204
|
+
| Dynamic routing | Requires condition logic |
|
|
205
|
+
| Transform before send | Covered by policy |
|
|
206
|
+
| Custom headers in API | Would add complexity |
|
|
207
|
+
| Multiple validators | One per flow sufficient |
|
|
208
|
+
|
|
209
|
+
---
|
|
210
|
+
|
|
211
|
+
## Data Flow Examples
|
|
212
|
+
|
|
213
|
+
### Order Complete (Server Flow)
|
|
214
|
+
|
|
215
|
+
1. **Ingest**: Request metadata extracted (IP, user-agent, referer) to
|
|
216
|
+
`context.*`
|
|
217
|
+
2. **Policy**: Pre-processes event:
|
|
218
|
+
- `user_data.em` from `user.email` (only if marketing consent)
|
|
219
|
+
- `user_data.external_id` from `user.id`
|
|
220
|
+
- `custom_data.server_processed` = `true`
|
|
221
|
+
- `custom_data.request_meta` = `{ ip, ua }` from context
|
|
222
|
+
3. **Fingerprint**: Hashes context fields to `user.hash`
|
|
223
|
+
4. **Validator**: Checks products have `data.id`
|
|
224
|
+
5. **Mapping**: Transforms to Meta format:
|
|
225
|
+
- `"name": "Purchase"`
|
|
226
|
+
- `value`, `currency`, `order_id` extracted
|
|
227
|
+
- `contents` via `$ref` to definition loop
|
|
228
|
+
|
|
229
|
+
### Product Add (Web Flow)
|
|
230
|
+
|
|
231
|
+
1. **DataLayer Source**: Captures `add_to_cart` event
|
|
232
|
+
2. **Source Mapping**: Transforms to `product add` with walkerOS structure
|
|
233
|
+
3. **Validator**: Checks `id` and `name` present
|
|
234
|
+
4. **Collector**: Adds globals, consent, user data
|
|
235
|
+
5. **GA4 Mapping**: Transforms to `add_to_cart` with items array
|
|
236
|
+
6. **API Destination**: Batches and sends to server (if batch size reached)
|
|
237
|
+
|
|
238
|
+
---
|
|
239
|
+
|
|
240
|
+
## Environment Variables
|
|
241
|
+
|
|
242
|
+
| Variable | Default | Description |
|
|
243
|
+
| -------------------- | ------------------------------- | -------------------------- |
|
|
244
|
+
| `GA4_MEASUREMENT_ID` | `G-DEMO123456` | Google Analytics 4 ID |
|
|
245
|
+
| `API_URL` | `http://localhost:8080/collect` | Server collection endpoint |
|
|
246
|
+
| `META_PIXEL_ID` | `123456789012345` | Meta Pixel ID |
|
|
247
|
+
| `META_ACCESS_TOKEN` | `demo_token` | Meta Conversions API token |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@walkeros/cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "1.0.1-next-1768820936934",
|
|
4
4
|
"description": "walkerOS CLI - Bundle and deploy walkerOS components",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -33,8 +33,8 @@
|
|
|
33
33
|
"docker:publish": "bash scripts/publish-docker.sh"
|
|
34
34
|
},
|
|
35
35
|
"dependencies": {
|
|
36
|
-
"@walkeros/core": "0.
|
|
37
|
-
"@walkeros/server-core": "0.
|
|
36
|
+
"@walkeros/core": "1.0.0",
|
|
37
|
+
"@walkeros/server-core": "1.0.0",
|
|
38
38
|
"chalk": "^5.6.2",
|
|
39
39
|
"commander": "^14.0.2",
|
|
40
40
|
"cors": "^2.8.5",
|
package/dist/walker.js
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
"use strict";(()=>{var o=Object.defineProperty;var s={};((t,e)=>{for(var n in e)o(t,n,{get:e[n],enumerable:!0})})(s,{Level:()=>r});var r=(t=>(t[t.ERROR=0]="ERROR",t[t.INFO=1]="INFO",t[t.DEBUG=2]="DEBUG",t))(r||{});})();
|