@walkeros/cli 4.9.0-next-1793116456867 → 4.9.0

package/dist/examples/README.md

@@ -54,17 +54,19 @@ walkeros push examples/flow-complete.json --flow web \
   --event '{"name":"page view","data":{"title":"Home"}}' \
   --consent '{"functional":true}' --simulate destination.ga4
 
-# The server flow needs GCP_SA, FINGERPRINT_SALT and EMAIL_SALT set (see the
-# setup in flow-complete.md) and a request context for its fingerprint step
+# The server flow needs GCP_SA, FINGERPRINT_SALT, EMAIL_SALT and
+# META_ACCESS_TOKEN set (see the setup in flow-complete.md) and a request
+# context for its fingerprint step
 walkeros push examples/flow-complete.json --flow server \
   --event '{"name":"page view","data":{"title":"Home"}}' \
   --ingest '{"ip":"203.0.113.7","userAgent":"Mozilla/5.0"}' \
   --simulate destination.pubsub
 ```
 
-Without `GCP_SA` a server simulation stops with
-`required secret "GCP_SA" is not set`; without `--ingest` the fingerprint step
-drops the event and Pub/Sub records `no calls`.
+Without one of these four secrets a server simulation stops, for example with
+`required secret "META_ACCESS_TOKEN" is not set`, whichever step you simulate;
+without `--ingest` the fingerprint step drops the event and Pub/Sub records
+`no calls`.
 
 ---
 

package/dist/examples/customers/README.md

@@ -14,8 +14,8 @@ folder's absolute path (always for `runneros start`, which runs inside the
 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`).
+`FINGERPRINT_SALT`, `EMAIL_SALT`, `META_ACCESS_TOKEN`).
 
 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
-change.
+`@walkeros/server-store-sheets`, a GCS store, or `@walkeros/server-store-api`
+for your CRM's API; the `loadUser` step does not change.

package/dist/examples/flow-complete.json

@@ -241,25 +241,25 @@
         "bundle": {
           "packages": {
             "@walkeros/collector": {
-              "version": "4.9.0-next-1793116456867"
+              "version": "4.9.0"
             },
             "@walkeros/web-source-cmp-usercentrics": {
-              "version": "4.9.0-next-1793116456867"
+              "version": "4.9.0"
             },
             "@walkeros/web-source-session": {
-              "version": "4.9.0-next-1793116456867"
+              "version": "4.9.0"
             },
             "@walkeros/web-source-datalayer": {
-              "version": "4.9.0-next-1793116456867"
+              "version": "4.9.0"
             },
             "@walkeros/web-source-browser": {
-              "version": "4.9.0-next-1793116456867"
+              "version": "4.9.0"
             },
             "@walkeros/web-destination-gtag": {
-              "version": "4.9.0-next-1793116456867"
+              "version": "4.9.0"
             },
             "@walkeros/web-destination-api": {
-              "version": "4.9.0-next-1793116456867"
+              "version": "4.9.0"
             }
           },
           "env": {
@@ -1778,40 +1778,40 @@
         "bundle": {
           "packages": {
             "@walkeros/collector": {
-              "version": "4.9.0-next-1793116456867"
+              "version": "4.9.0"
             },
             "@walkeros/server-source-express": {
-              "version": "4.9.0-next-1793116456867"
+              "version": "4.9.0"
             },
             "@walkeros/transformer-ga4": {
-              "version": "4.9.0-next-1793116456867"
+              "version": "4.9.0"
             },
             "@walkeros/transformer-validate": {
-              "version": "4.9.0-next-1793116456867"
+              "version": "4.9.0"
             },
             "@walkeros/server-transformer-bot": {
-              "version": "4.9.0-next-1793116456867"
+              "version": "4.9.0"
             },
             "@walkeros/server-transformer-fingerprint": {
-              "version": "4.9.0-next-1793116456867"
+              "version": "4.9.0"
             },
             "@walkeros/server-transformer-file": {
-              "version": "4.9.0-next-1793116456867"
+              "version": "4.9.0"
             },
             "@walkeros/server-store-fs": {
-              "version": "4.9.0-next-1793116456867"
+              "version": "4.9.0"
             },
             "@walkeros/server-destination-gcp": {
-              "version": "4.9.0-next-1793116456867"
+              "version": "4.9.0"
             },
             "@walkeros/server-destination-meta": {
-              "version": "4.9.0-next-1793116456867"
+              "version": "4.9.0"
             },
             "@walkeros/server-destination-piwikpro": {
-              "version": "4.9.0-next-1793116456867"
+              "version": "4.9.0"
             },
             "@walkeros/server-destination-datamanager": {
-              "version": "4.9.0-next-1793116456867"
+              "version": "4.9.0"
             }
           }
         }
@@ -1881,6 +1881,10 @@
                 {
                   "path": "/walker.js",
                   "methods": ["GET"]
+                },
+                {
+                  "path": "/demo/products/:id",
+                  "methods": ["GET"]
                 }
               ],
               "cors": {
@@ -1942,6 +1946,14 @@
                   "value": "/g/collect"
                 },
                 "stop": true
+              },
+              {
+                "match": {
+                  "key": "ingest.path",
+                  "operator": "prefix",
+                  "value": "/demo/products/"
+                },
+                "next": "productApi"
               }
             ]
           },
@@ -2412,6 +2424,7 @@
           },
           "config": {
             "settings": {
+              "prefix": "/",
               "headers": {
                 "Cache-Control": "public, max-age=300",
                 "Cross-Origin-Resource-Policy": "same-site"
@@ -2422,6 +2435,23 @@
             "stop": true
           }
         },
+        "productApi": {
+          "package": "@walkeros/server-transformer-file",
+          "env": {
+            "store": "$store.assets"
+          },
+          "config": {
+            "settings": {
+              "prefix": "/demo/",
+              "headers": {
+                "Content-Type": "application/json; charset=utf-8"
+              }
+            }
+          },
+          "next": {
+            "stop": true
+          }
+        },
         "dedup": {
           "cache": {
             "stop": true,
@@ -2558,7 +2588,7 @@
           "package": "@walkeros/server-transformer-fingerprint",
           "config": {
             "settings": {
-              "salt": "$env.FINGERPRINT_SALT",
+              "salt": "$secret.FINGERPRINT_SALT",
               "length": 16,
               "site": ["event.source.url", "ingest.origin"]
             }
@@ -4042,7 +4072,7 @@
           "package": "@walkeros/server-transformer-fingerprint",
           "config": {
             "settings": {
-              "salt": "$env.EMAIL_SALT",
+              "salt": "$secret.EMAIL_SALT",
               "rotate": "none",
               "output": "user.email",
               "fields": [
@@ -4304,7 +4334,7 @@
             },
             "settings": {
               "pixelId": "$env.META_PIXEL_ID:1234567890",
-              "accessToken": "$env.META_ACCESS_TOKEN",
+              "accessToken": "$secret.META_ACCESS_TOKEN",
               "action_source": "website",
               "user_data": {
                 "em": {
@@ -4852,13 +4882,13 @@
         "bundle": {
           "packages": {
             "@walkeros/collector": {
-              "version": "4.9.0-next-1793116456867"
+              "version": "4.9.0"
             },
             "@walkeros/server-source-gcp": {
-              "version": "4.9.0-next-1793116456867"
+              "version": "4.9.0"
             },
             "@walkeros/server-destination-gcp": {
-              "version": "4.9.0-next-1793116456867"
+              "version": "4.9.0"
             }
           }
         }

package/dist/examples/flow-complete.md

@@ -20,9 +20,9 @@ things.
   `.env` file. Run this once in the repo root before the server lines: `GCP_SA`
   holds a service account JSON (a throwaway key is enough for simulation: every
   Google client runs on its mock), `FINGERPRINT_SALT`, `EMAIL_SALT` and
-  `META_ACCESS_TOKEN` have no defaults on purpose, and `CUSTOMERS_DIR` points
-  the customers store at the demo data. Every other value is `$env.NAME:default`
-  and works out of the box.
+  `META_ACCESS_TOKEN` are secrets (`$secret.`) with no defaults, and
+  `CUSTOMERS_DIR` points the customers store at the demo data. Every other value
+  is `$env.NAME:default` and works out of the box.
 
 ```bash
 export CUSTOMERS_DIR="$PWD/packages/cli/examples/customers"
@@ -39,8 +39,8 @@ web      usercentrics, session, dataLayer, browser
            -> collector.next: opt-out stop, pageGroup
            -> ga4 (to Google, main property)  gtm (dataLayer)  collect (to server)
 
-server   express /collect  /g/collect  /walker.js
-           before: one [ G-SUBSITE hit -> ga4Decode -> ga4Consent | *.js -> file (stop) | other /g/collect (stop) ]
+server   express /collect  /g/collect  /walker.js  /demo/products/:id
+           before: one [ G-SUBSITE hit -> ga4Decode -> ga4Consent | *.js -> file (stop) | other /g/collect (stop) | /demo/products/ -> productApi (stop) ]
            next: opt-out stop, dedup
            -> collector.next: fingerprint, bot, not impression -> enrich [ loadUser, sessionSave, sessionLoad, validate ]
            -> pubsub (every event, email pseudonymized)
@@ -104,7 +104,8 @@ walkeros push packages/cli/examples/flow-complete.json -f web -e '{"name":"page
   - `datalayer-source` at `/flows/web/sources/dataLayer`: The dataLayer source
     reads the pushes the shop already makes, so nothing on the page changes.
   - `source-require` at `/flows/web/sources/dataLayer/config/require`: require
-    holds the source until consent and session are known.
+    holds back the entries already in the dataLayer until consent and session
+    are known; new pushes are captured from the start.
   - `source-mapping` at `/flows/web/sources/dataLayer/config/mapping`: Source
     mapping renames dataLayer add_to_cart to product add and picks its fields.
   - `browser-source` at `/flows/web/sources/browser`: The browser source reads
@@ -123,8 +124,9 @@ walkeros push packages/cli/examples/flow-complete.json -f web -e '{"name":"page
     flows reach it with $flow.
   - `config-settings` at `/flows/web/config/settings`: Platform settings:
     windowCollector names the global collector instance.
-- `require: ["consent", "session"]` on the dataLayer source means nothing is
-  read before the banner decision and the session are known.
+- `require: ["consent", "session"]` on the dataLayer source holds back the
+  entries already in the dataLayer until the banner decision and the session are
+  known. New pushes are captured at once.
 - The browser source is `primary`: its `elb` is the one the page calls.
 - Usercentrics and session examples are shown in the browser (their simulation
   in jsdom is still waiting), the dataLayer and browser examples simulate.
@@ -138,13 +140,14 @@ walkeros push packages/cli/examples/flow-complete.json -f web -e '{"name":"page
 ## server-entry: A first-party endpoint, and a GA4 migration path
 
 - **Purpose:** one express source answers the browser (`/collect`), GA4 hits of
-  a sub-site (`/g/collect`) and script requests (`/walker.js`).
+  a sub-site (`/g/collect`), script requests (`/walker.js`) and product lookups
+  (`/demo/products/:id`).
 - **Features:**
   - `server-url` at `/flows/server/config/url`: The full collect endpoint, local
     by default, SERVER_URL in production.
   - `express-paths` at `/flows/server/sources/express/config/settings/paths`:
     One route per job, each with its own methods: /collect, /g/collect,
-    /walker.js.
+    /walker.js, /demo/products/:id.
   - `express-cors` at `/flows/server/sources/express/config/settings/cors`: CORS
     response headers for the shop origin; express adds X-Content-Type-Options
     itself.
@@ -476,9 +479,9 @@ walkeros push packages/cli/examples/flow-complete.json -f server -e events/order
   - `ref-var-inline` at
     `/flows/warehouse/sources/pubsub/config/setup/deadLetterPolicy/deadLetterTopic`:
     Inside a longer string $var is replaced in place, here in a full topic name.
-  - `ref-env` at `/flows/server/transformers/fingerprint/config/settings/salt`:
-    $env without a default must be set: a secret salt never gets a public
-    default.
+  - `ref-env` at `/flows/web/collector/custom/environment`: $env without a
+    default must be set: this web flow declares ENVIRONMENT in
+    config.bundle.env, so the build never misses it.
   - `ref-env-default` at `/variables/gcp/project`: $env.NAME:default works out
     of the box and takes the environment value when set.
   - `ref-secret` at `/flows/server/destinations/pubsub/config/credentials`:
@@ -495,11 +498,13 @@ walkeros push packages/cli/examples/flow-complete.json -f server -e events/order
   - `ref-store` at `/flows/server/transformers/file/env/store`: $store.assets
     injects a store into a step.
   - `bundle-env` at `/flows/web/config/bundle/env`: Web $env is resolved at
-    build time from this declared set, so every build is the same.
+    build time: a local walkeros bundle reads the shell environment with this
+    declared set on top.
 - **Kinds:** `$var` (whole, deep, inline), `$env.NAME` and `$env.NAME:default`,
   `$secret`, `$flow`, `$code:`, `$contract`, `$store`.
-- **Secrets:** `$secret` is used only for `GCP_SA`, on the server and in the
-  warehouse; web flows reject `$secret`.
+- **Secrets:** `$secret` holds `GCP_SA` (server and warehouse) and, on the
+  server, `FINGERPRINT_SALT`, `EMAIL_SALT` and `META_ACCESS_TOKEN`; web flows
+  reject `$secret`.
 - **CLI:** `runneros` reads a private env file:
 
 ```bash
@@ -736,6 +741,15 @@ walkeros push packages/cli/examples/flow-complete.json -f server -e '{"name":"pa
     first party from the server flow.
   - `file-headers` at `/flows/server/transformers/file/config/settings/headers`:
     Default response headers for served files: caching and resource policy.
+  - `file-prefix` at `/flows/server/transformers/file/config/settings/prefix`:
+    prefix / makes the step own every script request: a missing walker.js
+    answers 404 instead of the tracking pixel.
+  - `products-case` at `/flows/server/sources/express/before/one/3`: The last
+    case sends product lookups (/demo/products/<id>) to productApi.
+  - `product-api` at `/flows/server/transformers/productApi`: A lookup route:
+    GET /demo/products/<id> answers the product as JSON from the assets store
+    (prefix /demo/ is stripped to the key products/<id>; headers sets the JSON
+    Content-Type), 404 for an unknown id, and never becomes an event.
   - `gclid-to-ads` at
     `/flows/server/destinations/datamanager/config/mapping/order/complete/data/map/gclid`:
     The gclid saved at session start reaches Google Ads with the purchase.
@@ -748,12 +762,27 @@ walkeros push packages/cli/examples/flow-complete.json -f server -e '{"name":"pa
   (`packages/cli/examples/customers`, one JSON record per customer id), outside
   root `include`, so no customer data ships in a bundle. `basePath` is relative
   to the working directory, so `CUSTOMERS_DIR` holds it as an absolute path (the
-  setup block at the top exports it). In production a Sheets or GCS store takes
-  its place; `loadUser` does not change.
+  setup block at the top exports it). In production a Sheets or GCS store, or
+  `@walkeros/server-store-api` for your CRM's API, takes its place; `loadUser`
+  does not change.
 - **walker.js first party:** the `file` transformer answers `GET /walker.js`
   from the `assets` store with `settings.headers` (`Cache-Control`,
   `Cross-Origin-Resource-Policy`) and ends with `next: { stop: true }`. Express
-  `settings.cors` adds the CORS headers.
+  `settings.cors` adds the CORS headers. With `prefix: "/"` the step owns every
+  script request: a missing `walker.js` answers 404 with
+  `Cache-Control: no-store` instead of the tracking pixel.
+- **A lookup route:** `productApi` is a second `file` step on the same `assets`
+  store. `GET /demo/products/SKU-1` answers 200 with the product as JSON
+  (`shared/products/SKU-1`; `settings.headers` sets the JSON `Content-Type`,
+  since the step serves bytes as stored), an unknown id answers 404 with
+  `Cache-Control: no-store`, and `next: { stop: true }` keeps every lookup from
+  becoming an event. A failing store read answers 503 and is logged at ERROR.
+
+```bash
+curl -i http://localhost:8080/demo/products/SKU-1
+curl -i http://localhost:8080/demo/products/SKU-9
+```
+
 - **Why `X-Content-Type-Options: nosniff` is not in the file:** express sets it
   on every response itself.
 - The `file` example is proven over HTTP in the integration test; its simulation

package/dist/examples/flow-selfhost-test.json

@@ -18,7 +18,9 @@
         "platform": "server",
         "bundle": {
           "packages": {
-            "@walkeros/collector": {}
+            "@walkeros/collector": {
+              "version": "latest"
+            }
           }
         }
       }

package/dist/examples/index.d.ts

@@ -970,7 +970,7 @@ declare const teaching: {
         pointer: string;
         chapter: "references";
         level: "intermediate";
-        useCases: "cookieless-id"[];
+        useCases: never[];
         note: string;
         docs: {
             page: string;
@@ -1700,6 +1700,30 @@ declare const teaching: {
             page: string;
         }[];
     };
+    'file-prefix': {
+        pointer: string;
+        chapter: "state-stores";
+        level: "intermediate";
+        useCases: "script-serving"[];
+        note: string;
+        docs: never[];
+    };
+    'products-case': {
+        pointer: string;
+        chapter: "state-stores";
+        level: "intermediate";
+        useCases: never[];
+        note: string;
+        docs: never[];
+    };
+    'product-api': {
+        pointer: string;
+        chapter: "state-stores";
+        level: "intermediate";
+        useCases: never[];
+        note: string;
+        docs: never[];
+    };
     'gclid-to-ads': {
         pointer: string;
         chapter: "state-stores";