@walkeros/cli 4.8.2 → 4.8.3-next-1793115089237

package/examples/contracts/saas.json

@@ -0,0 +1,229 @@
+{
+  "saas": {
+    "description": "Events of a SaaS product: trials and subscriptions.",
+    "extend": "default",
+    "schema": {
+      "description": "What every SaaS event adds.",
+      "type": "object",
+      "properties": {
+        "user": {
+          "type": "object",
+          "properties": {
+            "account": {
+              "type": "string",
+              "description": "The id of the company account the user belongs to.",
+              "examples": ["0e8c78ea9d97a7b8185e8632"]
+            }
+          }
+        }
+      }
+    },
+    "events": {
+      "trial": {
+        "start": {
+          "title": "Trial start",
+          "description": "A free trial of a paid plan began. Every SaaS product with trials needs it.",
+          "examples": [
+            {
+              "name": "trial start",
+              "data": {
+                "end": "2026-10-15T00:00:00Z"
+              },
+              "nested": [
+                {
+                  "entity": "plan",
+                  "data": {
+                    "id": "business",
+                    "name": "Business"
+                  }
+                }
+              ],
+              "user": {
+                "id": "us3r",
+                "account": "0e8c78ea9d97a7b8185e8632"
+              }
+            }
+          ],
+          "required": ["nested"],
+          "properties": {
+            "data": {
+              "type": "object",
+              "description": "The trial.",
+              "properties": {
+                "end": {
+                  "type": "string",
+                  "format": "date-time",
+                  "description": "When the trial ends.",
+                  "examples": ["2026-10-15T00:00:00Z"]
+                }
+              }
+            },
+            "nested": {
+              "type": "array",
+              "description": "The plan on trial.",
+              "contains": {
+                "type": "object",
+                "required": ["entity", "data"],
+                "properties": {
+                  "entity": {
+                    "type": "string",
+                    "enum": ["plan"],
+                    "description": "The entity name, plan.",
+                    "examples": ["plan"]
+                  },
+                  "data": {
+                    "type": "object",
+                    "description": "The plan.",
+                    "required": ["id"],
+                    "properties": {
+                      "id": {
+                        "type": ["string", "number"],
+                        "description": "The id of the plan.",
+                        "examples": ["business"]
+                      },
+                      "name": {
+                        "type": "string",
+                        "description": "The name of the plan.",
+                        "examples": ["Business"]
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "subscription": {
+        "start": {
+          "title": "Subscription start",
+          "description": "An account started to pay for a plan. Every SaaS product needs it. A renewal is no subscription start.",
+          "examples": [
+            {
+              "name": "subscription start",
+              "data": {
+                "id": "sub_9f21",
+                "value": 49,
+                "currency": "EUR",
+                "interval": "month"
+              },
+              "nested": [
+                {
+                  "entity": "plan",
+                  "data": {
+                    "id": "business",
+                    "name": "Business"
+                  }
+                }
+              ],
+              "user": {
+                "id": "us3r",
+                "account": "0e8c78ea9d97a7b8185e8632"
+              }
+            }
+          ],
+          "required": ["data", "nested"],
+          "properties": {
+            "data": {
+              "type": "object",
+              "description": "The subscription.",
+              "required": ["id", "value", "currency"],
+              "properties": {
+                "id": {
+                  "type": ["string", "number"],
+                  "description": "The id of the subscription.",
+                  "examples": ["sub_9f21"]
+                },
+                "value": {
+                  "type": "number",
+                  "description": "The amount of the first billing period, without tax.",
+                  "examples": [49]
+                },
+                "currency": {
+                  "type": "string",
+                  "description": "The currency of value, as a three-letter code.",
+                  "examples": ["EUR"]
+                },
+                "interval": {
+                  "type": "string",
+                  "description": "How often the subscription is billed, such as month or year.",
+                  "examples": ["month"]
+                }
+              }
+            },
+            "nested": {
+              "type": "array",
+              "description": "The plan subscribed to.",
+              "contains": {
+                "type": "object",
+                "required": ["entity", "data"],
+                "properties": {
+                  "entity": {
+                    "type": "string",
+                    "enum": ["plan"],
+                    "description": "The entity name, plan.",
+                    "examples": ["plan"]
+                  },
+                  "data": {
+                    "type": "object",
+                    "description": "The plan.",
+                    "required": ["id"],
+                    "properties": {
+                      "id": {
+                        "type": ["string", "number"],
+                        "description": "The id of the plan.",
+                        "examples": ["business"]
+                      },
+                      "name": {
+                        "type": "string",
+                        "description": "The name of the plan.",
+                        "examples": ["Business"]
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "cancel": {
+          "title": "Subscription cancel",
+          "description": "An account cancelled its subscription. Recommended for every SaaS product.",
+          "examples": [
+            {
+              "name": "subscription cancel",
+              "data": {
+                "id": "sub_9f21",
+                "reason": "too expensive"
+              },
+              "user": {
+                "id": "us3r",
+                "account": "0e8c78ea9d97a7b8185e8632"
+              }
+            }
+          ],
+          "required": ["data"],
+          "properties": {
+            "data": {
+              "type": "object",
+              "description": "The cancelled subscription.",
+              "required": ["id"],
+              "properties": {
+                "id": {
+                  "type": ["string", "number"],
+                  "description": "The id of the subscription.",
+                  "examples": ["sub_9f21"]
+                },
+                "reason": {
+                  "type": "string",
+                  "description": "Why the account cancelled.",
+                  "examples": ["too expensive"]
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/examples/contracts/travel.json

@@ -0,0 +1,234 @@
+{
+  "travel": {
+    "description": "Events of a travel booking site, from the trip being planned to the confirmed booking.",
+    "extend": "default",
+    "events": {
+      "itinerary": {
+        "add": {
+          "title": "Itinerary add",
+          "description": "A visitor added an experience or a destination to the trip they plan.",
+          "examples": [
+            {
+              "name": "itinerary add",
+              "data": {
+                "id": "it3m",
+                "type": "experience"
+              },
+              "trigger": "click"
+            }
+          ],
+          "required": ["data"],
+          "properties": {
+            "data": {
+              "type": "object",
+              "description": "The item added to the trip.",
+              "required": ["id", "type"],
+              "properties": {
+                "id": {
+                  "type": ["string", "number"],
+                  "description": "The id of the item.",
+                  "examples": ["it3m"]
+                },
+                "type": {
+                  "type": "string",
+                  "description": "What is booked, such as an experience or a destination.",
+                  "examples": ["experience"]
+                },
+                "title": {
+                  "type": "string",
+                  "description": "The name of what is booked."
+                },
+                "location": {
+                  "type": "string",
+                  "description": "Where it takes place."
+                },
+                "price": {
+                  "type": "number",
+                  "description": "The price per participant."
+                },
+                "currency": {
+                  "type": "string",
+                  "description": "The currency of every amount, as a three-letter code.",
+                  "examples": ["EUR"]
+                }
+              }
+            }
+          }
+        }
+      },
+      "booking": {
+        "start": {
+          "title": "Booking start",
+          "description": "A visitor began to book.",
+          "examples": [
+            {
+              "name": "booking start",
+              "data": {
+                "id": "b00k1ng",
+                "type": "experience"
+              },
+              "trigger": "click"
+            }
+          ],
+          "required": ["data"],
+          "properties": {
+            "data": {
+              "type": "object",
+              "description": "The booking.",
+              "required": ["id", "type"],
+              "properties": {
+                "id": {
+                  "type": ["string", "number"],
+                  "description": "The booking number.",
+                  "examples": ["b00k1ng"]
+                },
+                "type": {
+                  "type": "string",
+                  "description": "What is booked, such as an experience or a destination.",
+                  "examples": ["experience"]
+                },
+                "title": {
+                  "type": "string",
+                  "description": "The name of what is booked."
+                },
+                "location": {
+                  "type": "string",
+                  "description": "Where it takes place."
+                },
+                "price": {
+                  "type": "number",
+                  "description": "The price per participant."
+                },
+                "currency": {
+                  "type": "string",
+                  "description": "The currency of every amount, as a three-letter code.",
+                  "examples": ["EUR"]
+                }
+              }
+            }
+          }
+        },
+        "complete": {
+          "title": "Booking complete",
+          "description": "A booking was confirmed.",
+          "examples": [
+            {
+              "name": "booking complete",
+              "data": {
+                "id": "b00k1ng",
+                "type": "experience",
+                "start": "2026-11-12",
+                "end": "2026-11-15",
+                "participants": 2,
+                "insurance": false,
+                "value": 120,
+                "price": 60,
+                "currency": "EUR"
+              },
+              "trigger": "load"
+            }
+          ],
+          "required": ["data"],
+          "properties": {
+            "data": {
+              "type": "object",
+              "description": "The booking.",
+              "required": ["id", "value", "currency"],
+              "properties": {
+                "id": {
+                  "type": ["string", "number"],
+                  "description": "The booking number.",
+                  "examples": ["b00k1ng"]
+                },
+                "type": {
+                  "type": "string",
+                  "description": "What is booked, such as an experience or a destination.",
+                  "examples": ["experience"]
+                },
+                "title": {
+                  "type": "string",
+                  "description": "The name of what is booked."
+                },
+                "location": {
+                  "type": "string",
+                  "description": "Where it takes place."
+                },
+                "price": {
+                  "type": "number",
+                  "description": "The price per participant.",
+                  "examples": [60]
+                },
+                "currency": {
+                  "type": "string",
+                  "description": "The currency of every amount, as a three-letter code.",
+                  "examples": ["EUR"]
+                },
+                "start": {
+                  "type": "string",
+                  "format": "date",
+                  "description": "The first day of the booking.",
+                  "examples": ["2026-11-12"]
+                },
+                "end": {
+                  "type": "string",
+                  "format": "date",
+                  "description": "The last day of the booking.",
+                  "examples": ["2026-11-15"]
+                },
+                "participants": {
+                  "type": "number",
+                  "description": "How many people the booking is for.",
+                  "examples": [2]
+                },
+                "insurance": {
+                  "type": "boolean",
+                  "description": "True when the booking includes insurance.",
+                  "examples": [false]
+                },
+                "value": {
+                  "type": "number",
+                  "description": "The price times the participants.",
+                  "examples": [120]
+                }
+              }
+            }
+          }
+        }
+      },
+      "filter": {
+        "apply": {
+          "title": "Filter apply",
+          "description": "A visitor filtered a list of results.",
+          "examples": [
+            {
+              "name": "filter apply",
+              "data": {
+                "type": "price",
+                "option": "under 100"
+              },
+              "trigger": "click"
+            }
+          ],
+          "properties": {
+            "data": {
+              "type": "object",
+              "description": "The filter.",
+              "properties": {
+                "type": {
+                  "type": "string",
+                  "description": "What the filter works on, such as price.",
+                  "examples": ["price"]
+                },
+                "option": {
+                  "type": "string",
+                  "description": "The option chosen.",
+                  "examples": ["under 100"]
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/examples/customers/README.md

@@ -11,7 +11,10 @@ Not covered by root `include`, so no customer data ships in a bundle. `basePath`
 defaults to `./customers`, relative to the working directory: run
 `walkeros push` from `packages/cli/examples`, or set `CUSTOMERS_DIR` to this
 folder's absolute path (always for `runneros start`, which runs inside the
-artifact folder).
+artifact folder). From any other directory the lookup finds no file and the user
+gets no `ltv` or `segment`, without an error. A server flow simulation also
+needs the variables the setup in `flow-complete.md` exports (`GCP_SA`,
+`FINGERPRINT_SALT`, `EMAIL_SALT`).
 
 In production the store is swapped for a real one, e.g.
 `@walkeros/server-store-sheets` or a GCS store; the `loadUser` step does not

package/examples/flow-complete.json

@@ -241,25 +241,25 @@
         "bundle": {
           "packages": {
             "@walkeros/collector": {
-              "version": "4.8.2"
+              "version": "4.8.3-next-1793115089237"
             },
             "@walkeros/web-source-cmp-usercentrics": {
-              "version": "4.8.2"
+              "version": "4.8.3-next-1793115089237"
             },
             "@walkeros/web-source-session": {
-              "version": "4.8.2"
+              "version": "4.8.3-next-1793115089237"
             },
             "@walkeros/web-source-datalayer": {
-              "version": "4.8.2"
+              "version": "4.8.3-next-1793115089237"
             },
             "@walkeros/web-source-browser": {
-              "version": "4.8.2"
+              "version": "4.8.3-next-1793115089237"
             },
             "@walkeros/web-destination-gtag": {
-              "version": "4.8.2"
+              "version": "4.8.3-next-1793115089237"
             },
             "@walkeros/web-destination-api": {
-              "version": "4.8.2"
+              "version": "4.8.3-next-1793115089237"
             }
           },
           "env": {
@@ -305,7 +305,7 @@
           "examples": {
             "explicitDecision": {
               "title": "Explicit decision",
-              "description": "The user accepts every category in the banner. categoryMap turns essential and functional into functional, so the collector receives exactly the consent keys the contract names.",
+              "description": "The user accepts every category in the banner. categoryMap folds essential into functional so the collector receives exactly the consent keys the contract names; because any deny denies, functional still follows the functional category, and essential never grants it alone.",
               "public": true,
               "trigger": {
                 "type": "consent",
@@ -931,7 +931,14 @@
               "ga4": {
                 "measurementId": "$env.GA4_MEASUREMENT_ID:G-MAINSITE"
               },
-              "como": true
+              "como": {
+                "marketing": [
+                  "ad_storage",
+                  "ad_user_data",
+                  "ad_personalization"
+                ],
+                "functional": "analytics_storage"
+              }
             },
             "mapping": {
               "product": {
@@ -1419,6 +1426,14 @@
             "settings": {
               "gtm": {
                 "containerId": "$env.GTM_ID:GTM-SHOP01"
+              },
+              "como": {
+                "marketing": [
+                  "ad_storage",
+                  "ad_user_data",
+                  "ad_personalization"
+                ],
+                "functional": "analytics_storage"
               }
             },
             "mapping": {
@@ -1763,40 +1778,40 @@
         "bundle": {
           "packages": {
             "@walkeros/collector": {
-              "version": "4.8.2"
+              "version": "4.8.3-next-1793115089237"
             },
             "@walkeros/server-source-express": {
-              "version": "4.8.2"
+              "version": "4.8.3-next-1793115089237"
             },
             "@walkeros/transformer-ga4": {
-              "version": "4.8.2"
+              "version": "4.8.3-next-1793115089237"
             },
             "@walkeros/transformer-validate": {
-              "version": "4.8.2"
+              "version": "4.8.3-next-1793115089237"
             },
             "@walkeros/server-transformer-bot": {
-              "version": "4.8.2"
+              "version": "4.8.3-next-1793115089237"
             },
             "@walkeros/server-transformer-fingerprint": {
-              "version": "4.8.2"
+              "version": "4.8.3-next-1793115089237"
             },
             "@walkeros/server-transformer-file": {
-              "version": "4.8.2"
+              "version": "4.8.3-next-1793115089237"
             },
             "@walkeros/server-store-fs": {
-              "version": "4.8.2"
+              "version": "4.8.3-next-1793115089237"
             },
             "@walkeros/server-destination-gcp": {
-              "version": "4.8.2"
+              "version": "4.8.3-next-1793115089237"
             },
             "@walkeros/server-destination-meta": {
-              "version": "4.8.2"
+              "version": "4.8.3-next-1793115089237"
             },
             "@walkeros/server-destination-piwikpro": {
-              "version": "4.8.2"
+              "version": "4.8.3-next-1793115089237"
             },
             "@walkeros/server-destination-datamanager": {
-              "version": "4.8.2"
+              "version": "4.8.3-next-1793115089237"
             }
           }
         }
@@ -1882,7 +1897,7 @@
             },
             "ingest": {
               "map": {
-                "ip": "ip",
+                "ip": "headers.x-client-ip",
                 "path": "path",
                 "method": "method",
                 "url": "url",
@@ -4837,13 +4852,13 @@
         "bundle": {
           "packages": {
             "@walkeros/collector": {
-              "version": "4.8.2"
+              "version": "4.8.3-next-1793115089237"
             },
             "@walkeros/server-source-gcp": {
-              "version": "4.8.2"
+              "version": "4.8.3-next-1793115089237"
             },
             "@walkeros/server-destination-gcp": {
-              "version": "4.8.2"
+              "version": "4.8.3-next-1793115089237"
             }
           }
         }

package/examples/flow-complete.md

@@ -349,7 +349,8 @@ walkeros push packages/cli/examples/flow-complete.json -f web -e '{"name":"order
 - **Features:**
   - `cmp-category-map` at
     `/flows/web/sources/usercentrics/config/settings/categoryMap`: categoryMap
-    maps CMP categories onto exactly the consent keys the contract names.
+    maps CMP categories onto exactly the consent keys the contract names; folded
+    in, essential never grants functional alone.
   - `cmp-explicit-only` at
     `/flows/web/sources/usercentrics/config/settings/explicitOnly`: explicitOnly
     publishes consent only after a real decision, so consent.functional present
@@ -389,8 +390,9 @@ walkeros push packages/cli/examples/flow-complete.json -f web -e '{"name":"order
   - `pubsub-before` at `/flows/server/destinations/pubsub/before`: A conditional
     next on Pub/Sub runs pseudonymize only when an email exists; other events
     pass untouched.
-  - `ga4-como` at `/flows/web/destinations/ga4/config/settings/como`: como turns
-    walker consent into Google Consent Mode calls.
+  - `ga4-como` at `/flows/web/destinations/ga4/config/settings/como`: como maps
+    this flow's consent keys to Google Consent Mode: functional to
+    analytics_storage, marketing to the ad parameters.
 - **Consent keys:** there are no collector consent defaults, only granted keys
   travel. `consent.functional` is set only by Usercentrics with `explicitOnly`,
   so its presence means the user decided.

package/examples/shared/README.md

@@ -20,3 +20,7 @@ walkeros bundle packages/cli/examples/flow-complete.json -f web -o packages/cli/
 walkeros bundle packages/cli/examples/flow-complete.json -f server -o dist/server.mjs
 runneros start dist/server.mjs -p 8080 --env-file .env
 ```
+
+- `runneros` refuses an `.env` that group or other can read
+  (`Refusing to load env file ".env": it is readable by group or other`);
+  restrict it with `chmod 600 .env`.