@walkeros/cli 3.3.0 → 3.4.0-next-1776749829492

package/dist/examples/flow-complete.json

@@ -514,7 +514,8 @@
           "config": {
             "settings": {
               "url": "$var.apiUrl",
-              "batch": 5
+              "batch": 5,
+              "transform": "$code:(data) => JSON.stringify(data)"
             },
             "data": {
               "map": {
@@ -557,9 +558,7 @@
             "push": "$code:(event, ctx) => { ctx.logger.info('[DEBUG]', event.name, event.data); }"
           },
           "config": {
-            "consent": {
-              "functional": true
-            }
+            "consent": {}
           }
         }
       },
@@ -613,6 +612,7 @@
         "http": {
           "package": "@walkeros/server-source-express",
           "primary": true,
+          "next": ["filter"],
           "cache": {
             "store": "cache",
             "rules": [
@@ -643,7 +643,11 @@
               "context.ip": "ip",
               "context.userAgent": "headers.user-agent",
               "context.language": "headers.accept-language",
-              "context.referer": "headers.referer"
+              "context.referer": "headers.referer",
+              "context.anonymizedIp": {
+                "key": "ip",
+                "fn": "$code:(ip) => ip ? ip.replace(/\\.\\d+$/, '.0') : ''"
+              }
             }
           },
           "examples": {
@@ -682,6 +686,9 @@
             "push": "$code:(event) => event.name.startsWith('internal_') || event.name.startsWith('debug_') ? false : event"
           },
           "next": "fingerprint",
+          "env": {
+            "store": "$store:cache"
+          },
           "config": {},
           "examples": {
             "passes-normal": {
@@ -746,7 +753,7 @@
       "destinations": {
         "meta": {
           "package": "@walkeros/server-destination-meta",
-          "before": "fingerprint",
+          "before": ["fingerprint", "serverValidator"],
           "config": {
             "settings": {
               "pixelId": "$var.metaPixelId",
@@ -918,7 +925,8 @@
         "globals": {
           "environment": "demo",
           "version": "$var.flowVersion",
-          "platform": "server"
+          "platform": "server",
+          "startedAt": "$code:Date.now()"
         }
       },
       "bundle": {

package/dist/examples/flow-complete.md

@@ -11,19 +11,24 @@ complete event tracking architecture.
 │ WEB FLOW                                                                    │
 │                                                                             │
 │   Browser Source ─┐                                                         │
-│   DataLayer Source ──▶ [Validator] ──▶ Collector ──▶ GA4 Destination        │
-│   Demo Source ────┘                               └──▶ API Destination      │
-│                                                              │              │
-└──────────────────────────────────────────────────────────────│──────────────┘
-                                                               ▼
+│   DataLayer Source ──▶ [Enricher] ──▶ [Validator] ──▶ Collector ──▶ GA4     │
+│   Demo Source ────┘                                             ├──▶ API    │
+│                                                                 └──▶ Debug  │
+└─────────────────────────────────────────────────────────────────────────────┘
+
 ┌─────────────────────────────────────────────────────────────────────────────┐
 │ SERVER FLOW                                                                 │
 │                                                                             │
-│   HTTP Request ──▶ Express Source ──▶ Collector ──▶ [Fingerprint] ──────┐   │
-│                         │                          [Validator]          │   │
-│                         │                                               ▼   │
-│                         └── ingest: IP, user-agent ────────▶ Meta Destination
-│                                     language, referer       Demo Destination│
+│   HTTP Source ──▶ [Filter] ──▶ [Fingerprint] ──▶ [Validator] ──▶ Collector  │
+│        │              │                                          │          │
+│        │ ingest:      │ env:                    before:          ▼          │
+│        │ IP, UA,      │ $store:cache    [Fingerprint]+[Validator]           │
+│        │ lang, ref,   │                                          │          │
+│        │ anon-IP(fn)  │                                          ▼          │
+│        │              │                                   Meta Destination  │
+│        └──────────────┘                                   Demo Destination  │
+│                                                                             │
+│   Store: cache (memory, 10MB, 1000 entries)                                 │
 └─────────────────────────────────────────────────────────────────────────────┘
 ```
 
@@ -71,7 +76,7 @@ npx walkeros run packages/cli/examples/flow-complete.json --flow web
 
 ## Feature Inventory
 
-### Features Used (55)
+### Features Used (68)
 
 #### Mapping - Value Extraction
 
@@ -106,67 +111,81 @@ npx walkeros run packages/cli/examples/flow-complete.json --flow web
 
 #### Definitions & Variables
 
-| Feature              | Location           | Example                                      |
-| -------------------- | ------------------ | -------------------------------------------- |
-| Root-level variables | Root               | `"currency": "EUR"`                          |
-| Flow-level variables | server.variables   | `"metaPixelId": "${META_PIXEL_ID:...}"`      |
-| Environment variable | Variables          | `"${GA4_MEASUREMENT_ID:G-DEMO123456}"`       |
-| Env with default     | Variables          | `"${API_URL:http://localhost:8080/collect}"` |
-| $variables reference | GA4 settings       | `"$variables.ga4MeasurementId"`              |
-| Definition (complex) | Root definitions   | `"ga4ItemsLoop": { "loop": [...] }`          |
-| $ref reference       | GA4 purchase items | `{ "$ref": "#/definitions/ga4ItemsLoop" }`   |
+| Feature              | Location           | Example                                        |
+| -------------------- | ------------------ | ---------------------------------------------- |
+| Root-level variables | Root               | `"currency": "EUR"`                            |
+| Flow-level variables | server.variables   | `"metaPixelId": "$env.META_PIXEL_ID:..."`      |
+| Environment variable | Variables          | `"$env.GA4_MEASUREMENT_ID:G-DEMO123456"`       |
+| Env with default     | Variables          | `"$env.API_URL:http://localhost:8080/collect"` |
+| $var reference       | GA4 settings       | `"$var.ga4MeasurementId"`                      |
+| Definition (complex) | Root definitions   | `"ga4ItemsLoop": { "loop": [...] }`            |
+| $def reference       | GA4 purchase items | `"$def.ga4ItemsLoop"`                          |
+| $contract reference  | serverValidator    | `"$contract.default.events"`                   |
+| $store reference     | filter transformer | `"env": { "store": "$store:cache" }`           |
 
 #### Sources
 
-| Feature                 | Location  | Example                               |
-| ----------------------- | --------- | ------------------------------------- |
-| Primary source          | browser   | `"primary": true`                     |
-| Multiple sources        | web flow  | browser + dataLayer + demo            |
-| Source-level mapping    | dataLayer | `"mapping": { "add_to_cart": {...} }` |
-| Pre-collector chain     | dataLayer | `"next": "dataLayerValidator"`        |
-| Require (deferred init) | dataLayer | `"require": ["session"]`              |
-| Demo source events      | demo      | Pre-configured test events            |
+| Feature                 | Location      | Example                               |
+| ----------------------- | ------------- | ------------------------------------- |
+| Primary source          | browser       | `"primary": true`                     |
+| Multiple sources        | web flow      | browser + dataLayer + demo            |
+| Source-level mapping    | dataLayer     | `"mapping": { "add_to_cart": {...} }` |
+| Pre-collector chain     | dataLayer     | `"next": "enricher"`                  |
+| Pre-collector array     | http (server) | `"next": ["filter"]` (array form)     |
+| Require (deferred init) | dataLayer     | `"require": ["session"]`              |
+| Demo source events      | demo          | Pre-configured test events            |
 
 #### Transformers
 
-| Feature                 | Location           | Example                            |
-| ----------------------- | ------------------ | ---------------------------------- |
-| Validator transformer   | dataLayerValidator | JSON Schema validation             |
-| Fingerprint transformer | server             | Hash context fields to `user.hash` |
-| Transformer chaining    | server             | `"next": "serverValidator"`        |
-| Post-collector chain    | Meta               | `"before": "fingerprint"`          |
-| Contract validation     | serverValidator    | Entity/action schemas              |
-| Format option           | serverValidator    | `"format": true`                   |
+| Feature                 | Location           | Example                                        |
+| ----------------------- | ------------------ | ---------------------------------------------- |
+| Validator transformer   | dataLayerValidator | JSON Schema validation                         |
+| Fingerprint transformer | server             | Hash context fields to `user.hash`             |
+| Transformer chaining    | server             | `"next": "serverValidator"`                    |
+| Post-collector chain    | Meta               | `"before": ["fingerprint", "serverValidator"]` |
+| Contract validation     | serverValidator    | Entity/action schemas                          |
+| Format option           | serverValidator    | `"format": true`                               |
 
 #### Destinations
 
-| Feature                 | Location         | Example                            |
-| ----------------------- | ---------------- | ---------------------------------- |
-| Require (deferred init) | GA4              | `"require": ["consent", "user"]`   |
-| Destination consent     | GA4              | `"consent": { "marketing": true }` |
-| Destination mapping     | All destinations | Entity/action to vendor events     |
-| Multiple destinations   | Both flows       | GA4 + API, Meta + Demo             |
-| Batch option            | API              | `"batch": 5`                       |
+| Feature                 | Location         | Example                                 |
+| ----------------------- | ---------------- | --------------------------------------- |
+| Require (deferred init) | GA4              | `"require": ["consent", "user"]`        |
+| Destination consent     | GA4              | `"consent": { "marketing": true }`      |
+| Destination mapping     | All destinations | Entity/action to vendor events          |
+| Multiple destinations   | Both flows       | GA4 + API, Meta + Demo                  |
+| Batch option            | API              | `"batch": 5`                            |
+| Transform function      | API              | `"transform": "$code:(data) => ..."`    |
+| Empty consent (always)  | debug            | `"consent": {}` (fires without consent) |
 
 #### Collector
 
-| Feature           | Location        | Example                                 |
-| ----------------- | --------------- | --------------------------------------- |
-| Tagging           | Both collectors | `"tagging": 1`                          |
-| Consent defaults  | Both collectors | `"consent": { "functional": true }`     |
-| Globals           | Both collectors | `"environment": "demo"`                 |
-| Custom properties | web collector   | `"custom": { "campaign": "flow-demo" }` |
-| User defaults     | web collector   | `"user": { "id": "anonymous" }`         |
+| Feature           | Location         | Example                                 |
+| ----------------- | ---------------- | --------------------------------------- |
+| Tagging           | Both collectors  | `"tagging": 1`                          |
+| Consent defaults  | Both collectors  | `"consent": { "functional": true }`     |
+| Globals           | Both collectors  | `"environment": "demo"`                 |
+| Custom properties | web collector    | `"custom": { "campaign": "flow-demo" }` |
+| User defaults     | web collector    | `"user": { "id": "anonymous" }`         |
+| Dynamic global    | server collector | `"startedAt": "$code:Date.now()"`       |
 
 #### Server-Specific
 
-| Feature              | Location    | Example                                         |
-| -------------------- | ----------- | ----------------------------------------------- |
-| Ingest metadata      | http source | `"context.ip": "ip"`                            |
-| Language header      | ingest      | `"context.language": "headers.accept-language"` |
-| Policy               | Meta        | Pre-processing field transformation             |
-| Policy consent-gated | Meta        | `"user_data.em"` with consent                   |
-| Policy nested map    | Meta        | `"custom_data.request_meta": { "map": {...} }`  |
+| Feature               | Location        | Example                                                                 |
+| --------------------- | --------------- | ----------------------------------------------------------------------- |
+| Ingest metadata       | http source     | `"context.ip": "ip"`                                                    |
+| Language header       | ingest          | `"context.language": "headers.accept-language"`                         |
+| Ingest computed field | http source     | `"fn": "$code:(ip) => ip.replace(...)"`                                 |
+| Policy                | Meta            | Pre-processing field transformation                                     |
+| Policy consent-gated  | Meta            | `"user_data.em"` with consent                                           |
+| Policy nested map     | Meta            | `"custom_data.request_meta": { "map": {...} }`                          |
+| Local package path    | server packages | `"path": "../../core"` (resolve from filesystem)                        |
+| Source cache          | http source     | `"cache": { "store": "cache", "rules": [...] }`                         |
+| Cache match rule      | http source     | `"match": { "key": "ingest.method", "operator": "eq", "value": "GET" }` |
+| Cache TTL             | http source     | `"ttl": 300` (seconds)                                                  |
+| Cache response update | http source     | `"update": { "headers.X-Cache": { "key": "cache.status" } }`            |
+| Store definition      | server stores   | `"cache": { "package": "@walkeros/store-memory", ... }`                 |
+| Store settings        | cache store     | `"maxSize": 10485760, "maxEntries": 1000`                               |
 
 #### Browser Source
 

package/dist/index.d.ts

@@ -106,9 +106,23 @@ interface BuildOptions extends CLIBuildOptions {
     /**
      * Skip platform wrapper (Step 2) and output raw ESM.
      * Used by CLI push for direct import of the bundled module.
+     *
+     * @deprecated Use `target` option instead. `skipWrapper` conflates skeleton
+     * emission with /dev schema inclusion. See `BundleTarget` presets
+     * (`cdn` | `cdn-skeleton` | `runner` | `simulate` | `push`).
+     * Will be removed in the next major release.
+     *
      * @default false
      */
     skipWrapper?: boolean;
+    /**
+     * Include `@walkeros/*\/dev` imports for schema validation / simulate / push.
+     * Derived from the resolved `BundleTarget` preset by `bundle()`.
+     * If undefined, falls back to `skipWrapper === true` for backward compatibility
+     * with direct `bundleCore` callers (push, simulate) and legacy callers.
+     * @internal
+     */
+    withDev?: boolean;
     /**
      * Folders to include in the output directory.
      * These folders are copied alongside the bundle for runtime access.
@@ -165,6 +179,16 @@ interface BundleStats {
     treeshakingEffective: boolean;
 }
 
+/**
+ * Named bundle targets with frozen presets.
+ *
+ * A target is the ONLY input callers should pass. All internal booleans
+ * (skipWrapper, withDev, platform, env injection) derive from the preset.
+ * This prevents the class of bug where the same boolean means different
+ * things in different code paths (see: skipWrapper conflation, 2026-04-16).
+ */
+type BundleTarget = 'cdn' | 'cdn-skeleton' | 'runner' | 'simulate' | 'push';
+
 interface BundleCommandOptions {
     config?: string;
     output?: string;
@@ -216,6 +240,11 @@ declare function bundle(configOrPath: unknown, options?: {
     stats?: boolean;
     cache?: boolean;
     flowName?: string;
+    /**
+     * Named bundle target. If omitted, falls back to
+     * `buildOverrides.skipWrapper` mapping (deprecated) or `'cdn'`.
+     */
+    target?: BundleTarget;
     buildOverrides?: Partial<BuildOptions>;
 }): Promise<BundleStats | void>;
 /**
@@ -5116,20 +5145,58 @@ interface ApiErrorDetail {
     path: string;
     message: string;
 }
+interface ApiErrorOptions {
+    code?: string;
+    details?: ApiErrorDetail[];
+    minVersion?: string;
+    clientVersion?: string;
+    client?: string;
+    upgrade?: string;
+    docs?: string;
+}
 declare class ApiError extends Error {
     code?: string;
     details?: ApiErrorDetail[];
-    constructor(message: string, options?: {
-        code?: string;
-        details?: ApiErrorDetail[];
-    });
+    minVersion?: string;
+    clientVersion?: string;
+    client?: string;
+    upgrade?: string;
+    docs?: string;
+    constructor(message: string, options?: ApiErrorOptions);
 }
 /**
  * Extract structured error from an openapi-fetch error response and throw.
  * The error shape is: { error: { code, message, details: { errors: [] } } }
+ *
+ * For `code === 'CLIENT_OUTDATED'` (HTTP 426), also extracts the upgrade
+ * metadata: `minVersion`, `clientVersion`, `client`, `upgrade`, `docs`.
  */
 declare function throwApiError(error: unknown, fallbackMessage: string): never;
 
+type ClientType = 'cli' | 'mcp' | 'runner';
+interface ClientContext {
+    type: ClientType;
+    version: string;
+}
+/**
+ * Set the client context used to identify this process to the walkerOS app.
+ *
+ * The CLI binary calls this at startup, the MCP server calls it on boot, and
+ * the runner Docker image overrides the resolved type via the
+ * `WALKEROS_CLIENT_TYPE` env var (env wins over `input.type`).
+ */
+declare function setClientContext(input: {
+    type?: ClientType;
+    version: string;
+}): void;
+declare function getClientContext(): ClientContext | undefined;
+declare function resetClientContext(): void;
+/**
+ * Produce the outbound client-identification headers, or an empty object when
+ * no context has been set yet (e.g. in tests or pre-bootstrap code paths).
+ */
+declare function clientContextHeaders(): Record<string, string>;
+
 interface WalkerOSConfig {
     token: string;
     email: string;
@@ -5291,4 +5358,4 @@ interface PreparedFlow {
     cleanup: () => Promise<void>;
 }
 
-export { ApiError, type ApiErrorDetail, type BuildOptions, type BundleStats, type CLIBuildOptions, type DeployOptions, type ExampleLookupResult, type FeedbackOptions, type GlobalOptions, type ListDeploymentsOptions, type ListFlowsOptions, type MinifyOptions, type PrepareInput, type PreparedFlow, type PushResult, type RunCommandOptions, type RunOptions, type RunResult, type SSEEvent, type SSEParseResult, type SimulateDestinationOptions, type SimulateSourceOptions, type SimulateTransformerOptions, type ValidateResult, type ValidationError, type ValidationType, type ValidationWarning, type WalkerOSConfig, type WrapSkeletonOptions, apiFetch, bundle, bundleCommand, bundleRemote, compareOutput, createApiClient, createDeployCommand, createDeployment, createDeploymentCommand, createFlow, createFlowCommand, createProject, createProjectCommand, deleteDeployment, deleteDeploymentCommand, deleteFlow, deleteFlowCommand, deleteProject, deleteProjectCommand, deploy, deployCommand, deployFetch, duplicateFlow, duplicateFlowCommand, feedback, feedbackCommand, findExample, getAuthHeaders, getDeployment, getDeploymentBySlug, getDeploymentBySlugCommand, getDeploymentCommand, getFlow, getFlowCommand, getProject, getProjectCommand, getToken, listDeployments, listDeploymentsCommand, listFlows, listFlowsCommand, listProjects, listProjectsCommand, loadConfig, loadJsonConfig, loginCommand, logoutCommand, mergeAuthHeaders, parseSSEEvents, publicFetch, push, pushCommand, readConfig, requireProjectId, run, runCommand, simulateDestination, simulateSource, simulateTransformer, throwApiError, updateFlow, updateFlowCommand, updateProject, updateProjectCommand, validate, validateCommand, whoami, whoamiCommand, wrapSkeleton, writeConfig };
+export { ApiError, type ApiErrorDetail, type BuildOptions, type BundleStats, type CLIBuildOptions, type ClientContext, type ClientType, type DeployOptions, type ExampleLookupResult, type FeedbackOptions, type GlobalOptions, type ListDeploymentsOptions, type ListFlowsOptions, type MinifyOptions, type PrepareInput, type PreparedFlow, type PushResult, type RunCommandOptions, type RunOptions, type RunResult, type SSEEvent, type SSEParseResult, type SimulateDestinationOptions, type SimulateSourceOptions, type SimulateTransformerOptions, type ValidateResult, type ValidationError, type ValidationType, type ValidationWarning, type WalkerOSConfig, type WrapSkeletonOptions, apiFetch, bundle, bundleCommand, bundleRemote, clientContextHeaders, compareOutput, createApiClient, createDeployCommand, createDeployment, createDeploymentCommand, createFlow, createFlowCommand, createProject, createProjectCommand, deleteDeployment, deleteDeploymentCommand, deleteFlow, deleteFlowCommand, deleteProject, deleteProjectCommand, deploy, deployCommand, deployFetch, duplicateFlow, duplicateFlowCommand, feedback, feedbackCommand, findExample, getAuthHeaders, getClientContext, getDeployment, getDeploymentBySlug, getDeploymentBySlugCommand, getDeploymentCommand, getFlow, getFlowCommand, getProject, getProjectCommand, getToken, listDeployments, listDeploymentsCommand, listFlows, listFlowsCommand, listProjects, listProjectsCommand, loadConfig, loadJsonConfig, loginCommand, logoutCommand, mergeAuthHeaders, parseSSEEvents, publicFetch, push, pushCommand, readConfig, requireProjectId, resetClientContext, run, runCommand, setClientContext, simulateDestination, simulateSource, simulateTransformer, throwApiError, updateFlow, updateFlowCommand, updateProject, updateProjectCommand, validate, validateCommand, whoami, whoamiCommand, wrapSkeleton, writeConfig };