@walkeros/cli 0.3.5 → 0.4.0

package/examples/README.md

@@ -0,0 +1,330 @@
+# walkerOS Flow Examples
+
+This directory contains example flow configurations demonstrating various
+walkerOS use cases.
+
+## Rebuilding Example Bundles
+
+The `.mjs` bundle files in this directory are pre-built from their corresponding
+`.json` config files. If you update the configs or core packages, rebuild them:
+
+```bash
+cd /workspaces/walkerOS/packages/cli
+
+# Rebuild server-collect
+walkeros bundle examples/server-collect.json --local
+mv server-collect.mjs examples/
+
+# Rebuild web-serve
+walkeros bundle examples/web-serve.json --local
+mv web-serve.js examples/
+
+# Update Docker demos
+cp examples/server-collect.mjs ../docker/demos/demo-collect.mjs
+cp examples/web-serve.js ../docker/demos/demo-serve.mjs
+```
+
+**Important**: Always use `--local` flag when rebuilding examples in the
+devcontainer.
+
+## Web Examples
+
+### web-serve.json
+
+**Purpose**: Browser bundle that sends events to collector
+
+**Features**:
+
+- sourceDemo (generates test events automatically)
+- destinationDemo (console output for debugging)
+- destinationAPI (sends events to http://localhost:8080/collect)
+- Simulates page views and product views
+
+**Use case**: Demo web tracking that connects to server-collect.json for full
+event flow testing
+
+**Try it**:
+
+```bash
+walkeros bundle examples/web-serve.json
+walkeros run serve examples/web-serve.js -p 3000
+# Open http://localhost:3000 in browser
+```
+
+### web-tracking.json
+
+**Purpose**: Comprehensive browser tracking with multiple analytics platforms
+
+**Features**:
+
+- sourceBrowser (DOM event tracking)
+- destinationAPI → localhost:8080/collect (send to collection server)
+- destinationGtag → Google Analytics 4
+- destinationMeta → Meta Pixel (Facebook)
+- destinationDemo → Console logging
+
+**Event mappings**:
+
+- Page views → GA4 `page_view`, Meta `PageView`
+- Product views → GA4 `view_item`, Meta `ViewContent`
+- Add to cart → GA4 `add_to_cart`, Meta `AddToCart`
+- Purchases → GA4 `purchase`, Meta `Purchase`
+
+**Use case**: Production web tracking with multiple destinations
+
+**Environment variables**:
+
+- `GA4_MEASUREMENT_ID` - Google Analytics 4 measurement ID (default:
+  G-XXXXXXXXXX)
+- `META_PIXEL_ID` - Meta Pixel ID (default: 123456789)
+- `META_TEST_CODE` - Meta test event code (optional)
+
+**Try it**:
+
+```bash
+# Set environment variables
+export GA4_MEASUREMENT_ID="G-YOUR-ID"
+export META_PIXEL_ID="123456789"
+
+# Bundle for browser
+walkeros bundle examples/web-tracking.json --stats
+
+# Simulate events
+walkeros simulate examples/web-tracking.json \
+  --event '{"name":"product view","data":{"id":"P123","name":"Laptop","price":999}}'
+```
+
+## Server Examples
+
+### server-collect.json
+
+**Purpose**: Minimal server-side event collection endpoint
+
+**Features**:
+
+- sourceExpress (HTTP endpoint at /collect)
+- destinationDemo (console logging)
+- CORS enabled for browser requests
+- Health check endpoint
+
+**Use case**: Simple event collector for demo and testing, receives events from
+web-serve.json
+
+**Try it**:
+
+```bash
+walkeros bundle examples/server-collect.json
+walkeros run collect examples/server-collect.mjs -p 8080
+
+# In another terminal, send test event:
+curl -X POST http://localhost:8080/collect \
+  -H "Content-Type: application/json" \
+  -d '{"name":"page view","data":{"title":"Test"}}'
+```
+
+### server-collection.json
+
+**Purpose**: Server-side event collection and forwarding to data platforms
+
+**Features**:
+
+- sourceExpress (HTTP endpoint at /collect)
+- destinationDataManager → Google Tag Manager Server-Side
+- destinationDemo → Console logging
+
+**Event mappings**:
+
+- Page views → GTM `page_view`
+- Product views → GTM `view_item`
+- Add to cart → GTM `add_to_cart`
+- Purchases → GTM `purchase`
+
+**Use case**: Server-side tracking for privacy-compliant data collection
+
+**Environment variables**:
+
+- `GTM_CONTAINER_ID` - GTM Server Container ID (default: GTM-XXXXXXX)
+- `GTM_SERVER_URL` - GTM Server URL (default: https://gtm.example.com)
+
+**Try it**:
+
+```bash
+# Set environment variables
+export GTM_CONTAINER_ID="GTM-XXXXX"
+export GTM_SERVER_URL="https://your-gtm-server.com"
+
+# Run in Docker
+walkeros run collect examples/server-collection.json -p 8080
+
+# Send test event (in another terminal)
+curl -X POST http://localhost:8080/collect \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "product view",
+    "data": {
+      "id": "P123",
+      "name": "Laptop",
+      "price": 999
+    },
+    "user": {
+      "id": "user_123",
+      "session": "session_456"
+    }
+  }'
+```
+
+## Workflow: Web → Server
+
+### Quick Demo Loop (web-serve → server-collect)
+
+The simplest way to see the complete event flow:
+
+**Terminal 1 - Start collector**:
+
+```bash
+walkeros bundle examples/server-collect.json
+walkeros run collect examples/server-collect.mjs -p 8080
+```
+
+**Terminal 2 - Start web server**:
+
+```bash
+walkeros bundle examples/web-serve.json
+walkeros run serve examples/web-serve.js -p 3000
+```
+
+**Browser**: Open http://localhost:3000
+
+**Events flow**:
+
+```
+Browser (demo source) → destinationAPI → POST /collect → sourceExpress → destinationDemo (console)
+```
+
+### Production Pattern (web-tracking → server-collection)
+
+For production with real analytics platforms:
+
+**1. Start collection server**:
+
+```bash
+walkeros run collect examples/server-collection.json -p 8080
+```
+
+**2. Bundle web tracking** (configured to send to localhost:8080):
+
+```bash
+walkeros bundle examples/web-tracking.json
+```
+
+**3. Deploy** bundle to your website
+
+**4. Events flow**:
+
+```
+Browser → destinationAPI (POST /collect) → sourceExpress → destinationDataManager → GTM Server
+```
+
+## Creating Custom Examples
+
+### Flow Configuration Structure
+
+```json
+{
+  "flow": {
+    "platform": "web" | "server",
+    "sources": {
+      "<source_name>": {
+        "code": "<imported_function_name>",
+        "config": { "settings": { /* source config */ } }
+      }
+    },
+    "destinations": {
+      "<destination_name>": {
+        "code": "<imported_function_name>",
+        "config": {
+          "settings": { /* destination config */ },
+          "mapping": { /* event mappings */ }
+        }
+      }
+    },
+    "collector": {
+      "run": true,
+      "globals": { /* global properties */ }
+    }
+  },
+  "build": {
+    "packages": {
+      "<package_name>": {
+        "version": "latest",
+        "imports": ["<function_name>"]
+      }
+    },
+    "code": "// Optional custom code\n",
+    "template": "templates/base.hbs",
+    "output": "./dist/bundle.js"
+  }
+}
+```
+
+### Available Sources
+
+**Web**:
+
+- `@walkeros/web-source-browser` → `sourceBrowser` (DOM tracking)
+- `@walkeros/web-source-datalayer` → `sourceDataLayer` (data layer integration)
+- `@walkeros/source-demo` → `sourceDemo` (test events)
+
+**Server**:
+
+- `@walkeros/server-source-express` → `sourceExpress` (HTTP endpoint)
+- `@walkeros/server-source-gcp` → `sourceGCP` (Google Cloud Functions)
+
+### Available Destinations
+
+**Web**:
+
+- `@walkeros/web-destination-api` → `destinationAPI` (HTTP API)
+- `@walkeros/web-destination-gtag` → `destinationGtag` (GA4, GTM, Ads)
+- `@walkeros/web-destination-meta` → `destinationMeta` (Meta Pixel)
+- `@walkeros/web-destination-piwikpro` → `destinationPiwikPro`
+- `@walkeros/web-destination-plausible` → `destinationPlausible`
+
+**Server**:
+
+- `@walkeros/server-destination-datamanager` → `destinationDataManager` (GTM
+  Server-Side)
+- `@walkeros/server-destination-meta` → `destinationMeta` (Meta CAPI)
+- `@walkeros/server-destination-aws` → `destinationAWS`
+- `@walkeros/server-destination-gcp` → `destinationGCP`
+
+**Universal**:
+
+- `@walkeros/destination-demo` → `destinationDemo` (console logging)
+
+## Event Naming Convention
+
+**CRITICAL**: Events must follow the "ENTITY ACTION" format with space
+separation:
+
+✅ Correct:
+
+- `"page view"`
+- `"product add"`
+- `"order complete"`
+- `"button click"`
+
+❌ Wrong:
+
+- `"page_view"` (underscore)
+- `"purchase"` (missing entity)
+- `"add_to_cart"` (underscore)
+
+The event name is parsed as: `const [entity, action] = event.split(' ')`
+
+## Next Steps
+
+1. Try each example with `walkeros bundle` and `walkeros simulate`
+2. Modify examples to match your tracking requirements
+3. Create custom flow files for your use case
+4. Deploy to production (see [PUBLISHING.md](../docs/PUBLISHING.md))

package/examples/event.json

@@ -0,0 +1,53 @@
+{
+  "name": "order complete",
+  "data": {
+    "id": "ORD-2024-12345",
+    "total": 299.99,
+    "currency": "USD",
+    "tax": 24.99,
+    "shipping": 15.00
+  },
+  "user": {
+    "id": "user_abc123",
+    "email": "customer@example.com",
+    "gclid": "CjwKCAiA_xyz123ABC"
+  },
+  "source": {
+    "id": "https://example.com/thankyou.html?email=customer@example.com&order=ORD-2024-12345&gclid=CjwKCAiA_xyz123ABC",
+    "type": "web"
+  },
+  "nested": [
+    {
+      "type": "product",
+      "data": {
+        "id": "PROD-001",
+        "name": "Wireless Headphones",
+        "price": 149.99,
+        "quantity": 1,
+        "category": "Electronics"
+      }
+    },
+    {
+      "type": "product",
+      "data": {
+        "id": "PROD-002",
+        "name": "Phone Case",
+        "price": 29.99,
+        "quantity": 2,
+        "category": "Accessories"
+      }
+    }
+  ],
+  "consent": {
+    "functional": true,
+    "marketing": true
+  },
+  "globals": {
+    "language": "en",
+    "country": "US"
+  },
+  "context": {
+    "session": ["sess_xyz789", 1],
+    "page": ["/thankyou", 0]
+  }
+}

package/examples/flow-order-complete.json

@@ -0,0 +1,68 @@
+{
+  "flow": {
+    "platform": "web",
+    "destinations": {
+      "demo": {
+        "code": "destinationDemo",
+        "config": {
+          "consent": {
+            "marketing": true
+          },
+          "settings": {
+            "name": "Order Complete with Consent Demo",
+            "values": ["name", "data", "user", "source", "consent"]
+          },
+          "mapping": {
+            "order": {
+              "complete": {
+                "name": "purchase",
+                "data": {
+                  "map": {
+                    "transaction_id": "data.id",
+                    "value": "data.total",
+                    "currency": "data.currency",
+                    "tax": "data.tax",
+                    "shipping": "data.shipping",
+                    "email": {
+                      "key": "user.email",
+                      "consent": {
+                        "marketing": true
+                      }
+                    },
+                    "gclid": {
+                      "key": "user.gclid",
+                      "consent": {
+                        "marketing": true
+                      }
+                    },
+                    "source_url": "source.id"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "collector": {
+      "run": true,
+      "globals": {
+        "environment": "production",
+        "version": "1.0.0"
+      }
+    }
+  },
+  "build": {
+    "packages": {
+      "@walkeros/collector": {
+        "version": "latest",
+        "imports": ["startFlow"]
+      },
+      "@walkeros/destination-demo": {
+        "version": "latest",
+        "imports": ["destinationDemo"]
+      }
+    },
+    "output": "flow-order-complete.js"
+  }
+}

package/examples/flow-simple.json

@@ -0,0 +1,32 @@
+{
+  "flow": {
+    "platform": "web",
+    "destinations": {
+      "demo": {
+        "code": "destinationDemo",
+        "config": {
+          "settings": {
+            "name": "Simple Demo",
+            "values": ["name", "data", "user", "consent"]
+          }
+        }
+      }
+    },
+    "collector": {
+      "run": true
+    }
+  },
+  "build": {
+    "packages": {
+      "@walkeros/collector": {
+        "version": "latest",
+        "imports": ["startFlow"]
+      },
+      "@walkeros/destination-demo": {
+        "version": "latest",
+        "imports": ["destinationDemo"]
+      }
+    },
+    "output": "flow-simple.js"
+  }
+}

package/examples/flow.json

@@ -0,0 +1,82 @@
+{
+  "flow": {
+    "platform": "web",
+    "destinations": {
+      "ga4": {
+        "code": "destinationGtag",
+        "config": {
+          "consent": {
+            "marketing": true
+          },
+          "settings": {
+            "ga4": {
+              "measurementId": "G-XXXXXXXXXX"
+            }
+          },
+          "mapping": {
+            "order": {
+              "complete": {
+                "name": "purchase",
+                "data": {
+                  "map": {
+                    "transaction_id": "data.id",
+                    "value": "data.total",
+                    "currency": "data.currency",
+                    "tax": "data.tax",
+                    "shipping": "data.shipping",
+                    "email": {
+                      "key": "user.email",
+                      "consent": {
+                        "marketing": true
+                      }
+                    },
+                    "gclid": {
+                      "key": "user.gclid",
+                      "consent": {
+                        "marketing": true
+                      }
+                    },
+                    "source_url": "source.id"
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "demo": {
+        "code": "destinationDemo",
+        "config": {
+          "settings": {
+            "name": "Order Complete Demo",
+            "values": ["name", "data", "user", "source", "consent"]
+          }
+        }
+      }
+    },
+    "collector": {
+      "run": true,
+      "globals": {
+        "environment": "production",
+        "version": "1.0.0"
+      }
+    }
+  },
+  "build": {
+    "packages": {
+      "@walkeros/collector": {
+        "version": "latest",
+        "imports": ["startFlow"]
+      },
+      "@walkeros/web-destination-gtag": {
+        "version": "latest",
+        "imports": ["destinationGtag"]
+      },
+      "@walkeros/destination-demo": {
+        "version": "latest",
+        "imports": ["destinationDemo"]
+      }
+    },
+    "output": "flow.js"
+  }
+}

package/examples/server-collect.json

@@ -0,0 +1,53 @@
+{
+  "flow": {
+    "platform": "server",
+    "sources": {
+      "http": {
+        "code": "sourceExpress",
+        "config": {
+          "settings": {
+            "path": "/collect",
+            "port": 8080,
+            "cors": true,
+            "healthCheck": true
+          }
+        }
+      }
+    },
+    "destinations": {
+      "demo": {
+        "code": "destinationDemo",
+        "config": {
+          "settings": {
+            "name": "Server Collection Demo",
+            "values": ["name", "data", "context", "user", "nested", "timestamp"]
+          }
+        }
+      }
+    },
+    "collector": {
+      "run": true,
+      "globals": {
+        "environment": "test",
+        "version": "1.0.0"
+      }
+    }
+  },
+  "build": {
+    "packages": {
+      "@walkeros/collector": {
+        "version": "latest",
+        "imports": ["startFlow"]
+      },
+      "@walkeros/server-source-express": {
+        "version": "latest",
+        "imports": ["sourceExpress"]
+      },
+      "@walkeros/destination-demo": {
+        "version": "latest",
+        "imports": ["destinationDemo"]
+      }
+    },
+    "output": "server-collect.mjs"
+  }
+}