@walkeros/core 0.4.0 → 0.4.2

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 /**
  * Core collector configuration interface
  */
-interface Config$5 {
+interface Config$6 {
     /** Whether to run collector automatically */
     run?: boolean;
     /** Version for event tagging */
@@ -10,17 +10,13 @@ interface Config$5 {
     globalsStatic: Properties;
     /** Static session data even on a new run */
     sessionStatic: Partial<SessionData>;
-    /** Enable verbose logging */
-    verbose: boolean;
-    /** Error handler */
-    onError?: Error;
-    /** Log handler */
-    onLog?: Log;
+    /** Logger configuration */
+    logger?: Config$3;
 }
 /**
  * Initialization configuration that extends Config with initial state
  */
-interface InitConfig extends Partial<Config$5> {
+interface InitConfig extends Partial<Config$6> {
     /** Initial consent state */
     consent?: Consent;
     /** Initial user data */
@@ -50,7 +46,7 @@ interface Sources {
     [id: string]: Instance;
 }
 interface Destinations$1 {
-    [id: string]: Instance$1;
+    [id: string]: Instance$2;
 }
 type CommandType = 'action' | 'config' | 'consent' | 'context' | 'destination' | 'elb' | 'globals' | 'hook' | 'init' | 'link' | 'run' | 'user' | 'walker' | string;
 /**
@@ -69,9 +65,9 @@ interface PushFn$1 {
  * Command function signature - handles walker commands only
  */
 interface CommandFn {
-    (command: 'config', config: Partial<Config$5>): Promise<PushResult>;
+    (command: 'config', config: Partial<Config$6>): Promise<PushResult>;
     (command: 'consent', consent: Consent): Promise<PushResult>;
-    <T extends Types$2>(command: 'destination', destination: Init$1<T> | Instance$1<T>, config?: Config$4<T>): Promise<PushResult>;
+    <T extends Types$2>(command: 'destination', destination: Init$1<T> | Instance$2<T>, config?: Config$5<T>): Promise<PushResult>;
     <K extends keyof Functions>(command: 'hook', name: K, hookFn: Functions[K]): Promise<PushResult>;
     (command: 'on', type: Types$1, rules: SingleOrArray<Options>): Promise<PushResult>;
     (command: 'user', user: User): Promise<PushResult>;
@@ -83,11 +79,11 @@ interface CommandFn {
     }): Promise<PushResult>;
     (command: string, data?: unknown, options?: unknown): Promise<PushResult>;
 }
-interface Instance$2 {
+interface Instance$3 {
     push: PushFn$1;
     command: CommandFn;
     allowed: boolean;
-    config: Config$5;
+    config: Config$6;
     consent: Consent;
     count: number;
     custom: Properties;
@@ -96,6 +92,7 @@ interface Instance$2 {
     globals: Properties;
     group: string;
     hooks: Functions;
+    logger: Instance$1;
     on: OnConfig;
     queue: Events;
     round: number;
@@ -111,7 +108,7 @@ type collector_InitConfig = InitConfig;
 type collector_SessionData = SessionData;
 type collector_Sources = Sources;
 declare namespace collector {
-  export type { collector_CommandFn as CommandFn, collector_CommandType as CommandType, Config$5 as Config, Destinations$1 as Destinations, collector_InitConfig as InitConfig, Instance$2 as Instance, PushContext$1 as PushContext, PushFn$1 as PushFn, collector_SessionData as SessionData, collector_Sources as Sources };
+  export type { collector_CommandFn as CommandFn, collector_CommandType as CommandType, Config$6 as Config, Destinations$1 as Destinations, collector_InitConfig as InitConfig, Instance$3 as Instance, PushContext$1 as PushContext, PushFn$1 as PushFn, collector_SessionData as SessionData, collector_Sources as Sources };
 }
 
 interface Contract$1 {
@@ -182,10 +179,11 @@ interface BaseEnv$1 {
 }
 /**
  * Type bundle for destination generics.
- * Groups Settings, Mapping, and Env into a single type parameter.
+ * Groups Settings, InitSettings, Mapping, and Env into a single type parameter.
  */
-interface Types$2<S = unknown, M = unknown, E = BaseEnv$1> {
+interface Types$2<S = unknown, M = unknown, E = BaseEnv$1, I = S> {
     settings: S;
+    initSettings: I;
     mapping: M;
     env: E;
 }
@@ -194,6 +192,7 @@ interface Types$2<S = unknown, M = unknown, E = BaseEnv$1> {
  */
 type TypesGeneric$1 = {
     settings: any;
+    initSettings: any;
     mapping: any;
     env: any;
 };
@@ -201,14 +200,15 @@ type TypesGeneric$1 = {
  * Type extractors for consistent usage with Types bundle
  */
 type Settings$1<T extends TypesGeneric$1 = Types$2> = T['settings'];
+type InitSettings$1<T extends TypesGeneric$1 = Types$2> = T['initSettings'];
 type Mapping$1<T extends TypesGeneric$1 = Types$2> = T['mapping'];
 type Env$1<T extends TypesGeneric$1 = Types$2> = T['env'];
 /**
  * Inference helper: Extract Types from Instance
  */
-type TypesOf$1<I> = I extends Instance$1<infer T> ? T : never;
-interface Instance$1<T extends TypesGeneric$1 = Types$2> {
-    config: Config$4<T>;
+type TypesOf$1<I> = I extends Instance$2<infer T> ? T : never;
+interface Instance$2<T extends TypesGeneric$1 = Types$2> {
+    config: Config$5<T>;
     queue?: Events;
     dlq?: DLQ;
     type?: string;
@@ -218,47 +218,47 @@ interface Instance$1<T extends TypesGeneric$1 = Types$2> {
     pushBatch?: PushBatchFn<T>;
     on?: OnFn;
 }
-interface Config$4<T extends TypesGeneric$1 = Types$2> {
+interface Config$5<T extends TypesGeneric$1 = Types$2> {
     consent?: Consent;
-    settings?: Settings$1<T>;
+    settings?: InitSettings$1<T>;
     data?: Value | Values;
     env?: Env$1<T>;
     id?: string;
     init?: boolean;
     loadScript?: boolean;
+    logger?: Config$3;
     mapping?: Rules<Rule<Mapping$1<T>>>;
     policy?: Policy$1;
     queue?: boolean;
-    verbose?: boolean;
-    onError?: Error;
-    onLog?: Log;
 }
-type PartialConfig$1<T extends TypesGeneric$1 = Types$2> = Config$4<Types$2<Partial<Settings$1<T>> | Settings$1<T>, Partial<Mapping$1<T>> | Mapping$1<T>, Env$1<T>>>;
+type PartialConfig$1<T extends TypesGeneric$1 = Types$2> = Config$5<Types$2<Partial<Settings$1<T>> | Settings$1<T>, Partial<Mapping$1<T>> | Mapping$1<T>, Env$1<T>>>;
 interface Policy$1 {
     [key: string]: Value;
 }
 type Init$1<T extends TypesGeneric$1 = Types$2> = {
-    code: Instance$1<T>;
-    config?: Partial<Config$4<T>>;
+    code: Instance$2<T>;
+    config?: Partial<Config$5<T>>;
     env?: Partial<Env$1<T>>;
 };
 interface InitDestinations {
     [key: string]: Init$1<any>;
 }
 interface Destinations {
-    [key: string]: Instance$1;
+    [key: string]: Instance$2;
 }
 interface Context$2<T extends TypesGeneric$1 = Types$2> {
-    collector: Instance$2;
-    config: Config$4<T>;
+    collector: Instance$3;
+    config: Config$5<T>;
     data?: Data$1;
     env: Env$1<T>;
+    logger: Instance$1;
 }
 interface InitContext<T extends TypesGeneric$1 = Types$2> {
-    collector: Instance$2;
-    config: Config$4<Types$2<Partial<Settings$1<T>>, Mapping$1<T>, Env$1<T>>>;
+    collector: Instance$3;
+    config: Config$5<Types$2<Partial<Settings$1<T>>, Mapping$1<T>, Env$1<T>>>;
     data?: Data$1;
     env: Env$1<T>;
+    logger: Instance$1;
 }
 interface PushContext<T extends TypesGeneric$1 = Types$2> extends Context$2<T> {
     mapping?: Rule<Mapping$1<T>>;
@@ -266,7 +266,7 @@ interface PushContext<T extends TypesGeneric$1 = Types$2> extends Context$2<T> {
 interface PushBatchContext<T extends TypesGeneric$1 = Types$2> extends Context$2<T> {
     mapping?: Rule<Mapping$1<T>>;
 }
-type InitFn<T extends TypesGeneric$1 = Types$2> = (context: InitContext<T>) => PromiseOrValue<void | false | Config$4<T>>;
+type InitFn<T extends TypesGeneric$1 = Types$2> = (context: InitContext<T>) => PromiseOrValue<void | false | Config$5<T>>;
 type PushFn<T extends TypesGeneric$1 = Types$2> = (event: Event, context: PushContext<T>) => PromiseOrValue<void>;
 type PushBatchFn<T extends TypesGeneric$1 = Types$2> = (batch: Batch<Mapping$1<T>>, context: PushBatchContext<T>) => void;
 type PushEvent<Mapping = unknown> = {
@@ -283,7 +283,7 @@ interface Batch<Mapping> {
 type Data$1 = Property | undefined | Array<Property | undefined>;
 type Ref = {
     id: string;
-    destination: Instance$1;
+    destination: Instance$2;
 };
 type Push$1 = {
     queue?: Events;
@@ -310,7 +310,7 @@ type destination_PushEvents<Mapping = unknown> = PushEvents<Mapping>;
 type destination_PushFn<T extends TypesGeneric$1 = Types$2> = PushFn<T>;
 type destination_Ref = Ref;
 declare namespace destination {
-  export type { BaseEnv$1 as BaseEnv, destination_Batch as Batch, Config$4 as Config, Context$2 as Context, destination_DLQ as DLQ, Data$1 as Data, destination_Destinations as Destinations, Env$1 as Env, Init$1 as Init, destination_InitContext as InitContext, destination_InitDestinations as InitDestinations, destination_InitFn as InitFn, Instance$1 as Instance, Mapping$1 as Mapping, PartialConfig$1 as PartialConfig, Policy$1 as Policy, Push$1 as Push, destination_PushBatchContext as PushBatchContext, destination_PushBatchFn as PushBatchFn, destination_PushContext as PushContext, destination_PushEvent as PushEvent, destination_PushEvents as PushEvents, destination_PushFn as PushFn, destination_Ref as Ref, Result$1 as Result, Settings$1 as Settings, Types$2 as Types, TypesGeneric$1 as TypesGeneric, TypesOf$1 as TypesOf };
+  export type { BaseEnv$1 as BaseEnv, destination_Batch as Batch, Config$5 as Config, Context$2 as Context, destination_DLQ as DLQ, Data$1 as Data, destination_Destinations as Destinations, Env$1 as Env, Init$1 as Init, destination_InitContext as InitContext, destination_InitDestinations as InitDestinations, destination_InitFn as InitFn, InitSettings$1 as InitSettings, Instance$2 as Instance, Mapping$1 as Mapping, PartialConfig$1 as PartialConfig, Policy$1 as Policy, Push$1 as Push, destination_PushBatchContext as PushBatchContext, destination_PushBatchFn as PushBatchFn, destination_PushContext as PushContext, destination_PushEvent as PushEvent, destination_PushEvents as PushEvents, destination_PushFn as PushFn, destination_Ref as Ref, Result$1 as Result, Settings$1 as Settings, Types$2 as Types, TypesGeneric$1 as TypesGeneric, TypesOf$1 as TypesOf };
 }
 
 interface EventFn<R = Promise<PushResult>> {
@@ -323,7 +323,7 @@ interface Fn$1<R = Promise<PushResult>, Config = unknown> extends EventFn<R>, Wa
 interface WalkerCommands<R = Promise<PushResult>, Config = unknown> {
     (event: 'walker config', config: Partial<Config>): R;
     (event: 'walker consent', consent: Consent): R;
-    <T extends Types$2>(event: 'walker destination', destination: Init$1<T> | Instance$1<T>, config?: Config$4<T>): R;
+    <T extends Types$2>(event: 'walker destination', destination: Init$1<T> | Instance$2<T>, config?: Config$5<T>): R;
     <K extends keyof Functions>(event: 'walker hook', name: K, hookFn: Functions[K]): R;
     (event: 'walker on', type: Types$1, rules: SingleOrArray<Options>): R;
     (event: 'walker user', user: User): R;
@@ -358,7 +358,7 @@ declare namespace elb {
  * Platform-agnostic, runtime-focused.
  *
  * The Flow system enables "one config to rule them all" - a single
- * walkeros.config.json file that manages multiple environments
+ * walkeros.config.json file that manages multiple flows
  * (web_prod, web_stage, server_prod, etc.) with shared configuration,
  * variables, and reusable definitions.
  *
@@ -370,25 +370,68 @@ declare namespace elb {
  */
 type Primitive = string | number | boolean;
 /**
- * Complete multi-environment configuration.
- * This is the root type for walkeros.config.json files.
+ * Variables record type for interpolation.
+ * Used at Setup, Config, Source, and Destination levels.
+ */
+type Variables = Record<string, Primitive>;
+/**
+ * Definitions record type for reusable configurations.
+ * Used at Setup, Config, Source, and Destination levels.
+ */
+type Definitions = Record<string, unknown>;
+/**
+ * Packages configuration for build.
+ */
+type Packages = Record<string, {
+    version?: string;
+    imports?: string[];
+    path?: string;
+}>;
+/**
+ * Web platform configuration.
+ *
+ * @remarks
+ * Presence of this key indicates web platform (browser-based tracking).
+ * Builds to IIFE format, ES2020 target, browser platform.
+ */
+interface Web {
+    /**
+     * Window property name for collector instance.
+     * @default "collector"
+     */
+    windowCollector?: string;
+    /**
+     * Window property name for elb function.
+     * @default "elb"
+     */
+    windowElb?: string;
+}
+/**
+ * Server platform configuration.
+ *
+ * @remarks
+ * Presence of this key indicates server platform (Node.js).
+ * Builds to ESM format, Node18 target, node platform.
+ * Reserved for future server-specific options.
+ */
+interface Server {
+}
+/**
+ * Complete multi-flow configuration.
+ * Root type for walkeros.config.json files.
  *
  * @remarks
- * The Setup interface represents the entire configuration file,
- * containing multiple named environments that can share variables
- * and definitions.
+ * If only one flow exists, it's auto-selected without --flow flag.
+ * Convention: use "default" as the flow name for single-flow configs.
  *
  * @example
  * ```json
  * {
  *   "version": 1,
  *   "$schema": "https://walkeros.io/schema/flow/v1.json",
- *   "variables": {
- *     "CURRENCY": "USD"
- *   },
- *   "environments": {
- *     "web_prod": { "platform": "web", ... },
- *     "server_prod": { "platform": "server", ... }
+ *   "variables": { "CURRENCY": "USD" },
+ *   "flows": {
+ *     "default": { "web": {}, ... }
  *   }
  * }
  * ```
@@ -396,141 +439,71 @@ type Primitive = string | number | boolean;
 interface Setup {
     /**
      * Configuration schema version.
-     * Used for compatibility checks and migrations.
-     *
-     * @remarks
-     * - Version 1: Initial Flow configuration system
-     * - Future versions will be documented as they're released
      */
     version: 1;
     /**
-     * JSON Schema reference for IDE validation and autocomplete.
-     *
-     * @remarks
-     * When set, IDEs like VSCode will provide:
-     * - Autocomplete for all fields
-     * - Inline documentation
-     * - Validation errors before deployment
-     *
-     * @example
-     * "$schema": "https://walkeros.io/schema/flow/v1.json"
+     * JSON Schema reference for IDE validation.
+     * @example "https://walkeros.io/schema/flow/v1.json"
      */
     $schema?: string;
     /**
-     * Shared variables for interpolation across all environments.
+     * Folders to include in the bundle output.
+     * These folders are copied to dist/ during bundle, making them available
+     * at runtime for both local and Docker execution.
      *
      * @remarks
-     * Variables can be referenced using `${VAR_NAME:default}` syntax.
-     * Resolution order:
-     * 1. Environment variable (process.env.VAR_NAME)
-     * 2. Config variable (config.variables.VAR_NAME)
-     * 3. Inline default value
+     * Use for credential files, configuration, or other runtime assets.
+     * Paths are relative to the config file location.
+     * Default: `["./shared"]` if the folder exists, otherwise `[]`.
      *
      * @example
      * ```json
      * {
-     *   "variables": {
-     *     "CURRENCY": "USD",
-     *     "GA4_ID": "G-DEFAULT"
-     *   },
-     *   "environments": {
-     *     "prod": {
-     *       "collector": {
-     *         "globals": {
-     *           "currency": "${CURRENCY}"
-     *         }
-     *       }
-     *     }
-     *   }
+     *   "include": ["./credentials", "./config"]
      * }
      * ```
      */
-    variables?: Record<string, Primitive>;
+    include?: string[];
+    /**
+     * Shared variables for interpolation.
+     * Resolution: process.env > Config.variables > Setup.variables > inline default
+     * Syntax: ${VAR_NAME} or ${VAR_NAME:default}
+     */
+    variables?: Variables;
     /**
      * Reusable configuration definitions.
-     *
-     * @remarks
-     * Definitions can be referenced using JSON Schema `$ref` syntax.
-     * Useful for sharing mapping rules, common settings, etc.
-     *
-     * @example
-     * ```json
-     * {
-     *   "definitions": {
-     *     "gtag_base_mapping": {
-     *       "page": {
-     *         "view": { "name": "page_view" }
-     *       }
-     *     }
-     *   },
-     *   "environments": {
-     *     "prod": {
-     *       "destinations": {
-     *         "gtag": {
-     *           "config": {
-     *             "mapping": { "$ref": "#/definitions/gtag_base_mapping" }
-     *           }
-     *         }
-     *       }
-     *     }
-     *   }
-     * }
-     * ```
+     * Referenced via JSON Schema $ref syntax: { "$ref": "#/definitions/name" }
      */
-    definitions?: Record<string, unknown>;
+    definitions?: Definitions;
     /**
-     * Named environment configurations.
-     *
-     * @remarks
-     * Each environment represents a deployment target:
-     * - web_prod, web_stage, web_dev (client-side tracking)
-     * - server_prod, server_stage (server-side collection)
-     *
-     * Environment names are arbitrary and user-defined.
-     *
-     * @example
-     * ```json
-     * {
-     *   "environments": {
-     *     "web_prod": {
-     *       "platform": "web",
-     *       "sources": { ... },
-     *       "destinations": { ... }
-     *     },
-     *     "server_prod": {
-     *       "platform": "server",
-     *       "destinations": { ... }
-     *     }
-     *   }
-     * }
-     * ```
+     * Named flow configurations.
+     * If only one flow exists, it's auto-selected.
      */
-    environments: Record<string, Config$3>;
+    flows: Record<string, Config$4>;
 }
 /**
- * Single environment configuration.
+ * Single flow configuration.
  * Represents one deployment target (e.g., web_prod, server_stage).
  *
  * @remarks
- * This is the core runtime configuration used by `startFlow()`.
- * Platform-agnostic and independent of build/deployment tools.
+ * Platform is determined by presence of `web` or `server` key.
+ * Exactly one must be present.
  *
- * Extensions (build, docker, etc.) are added via `[key: string]: unknown`.
+ * Variables/definitions cascade: source/destination > config > setup
  */
-interface Config$3 {
+interface Config$4 {
     /**
-     * Target platform for this environment.
-     *
-     * @remarks
-     * - `web`: Browser-based tracking (IIFE bundles, browser sources)
-     * - `server`: Node.js server-side collection (CJS bundles, HTTP sources)
-     *
-     * This determines:
-     * - Available packages (web-* vs server-*)
-     * - Default build settings
-     * - Template selection
+     * Web platform configuration.
+     * Presence indicates web platform (browser-based tracking).
+     * Mutually exclusive with `server`.
+     */
+    web?: Web;
+    /**
+     * Server platform configuration.
+     * Presence indicates server platform (Node.js).
+     * Mutually exclusive with `web`.
      */
-    platform: 'web' | 'server';
+    server?: Server;
     /**
      * Source configurations (data capture).
      *
@@ -625,35 +598,19 @@ interface Config$3 {
      */
     collector?: InitConfig;
     /**
-     * Environment-specific variables.
-     *
-     * @remarks
-     * These override root-level variables for this specific environment.
-     * Useful for environment-specific API keys, endpoints, etc.
-     *
-     * @example
-     * ```json
-     * {
-     *   "env": {
-     *     "API_ENDPOINT": "https://api.production.com",
-     *     "DEBUG": "false"
-     *   }
-     * }
-     * ```
+     * NPM packages to bundle.
      */
-    env?: Record<string, string>;
+    packages?: Packages;
     /**
-     * Extension point for package-specific fields.
-     *
-     * @remarks
-     * Allows packages to add their own configuration fields:
-     * - CLI adds `build` field (Bundle.Config)
-     * - Docker adds `docker` field (Docker.Config)
-     * - Lambda adds `lambda` field (Lambda.Config)
-     *
-     * Core doesn't validate these fields - packages handle validation.
+     * Flow-level variables.
+     * Override Setup.variables, overridden by source/destination variables.
      */
-    [key: string]: unknown;
+    variables?: Variables;
+    /**
+     * Flow-level definitions.
+     * Extend Setup.definitions, overridden by source/destination definitions.
+     */
+    definitions?: Definitions;
 }
 /**
  * Source reference with inline package syntax.
@@ -682,6 +639,14 @@ interface SourceReference {
      * "package": "@walkeros/web-source-browser@latest"
      */
     package: string;
+    /**
+     * Resolved import variable name.
+     *
+     * @remarks
+     * Auto-resolved from packages[package].imports[0] during getFlowConfig().
+     * Can also be provided explicitly for advanced use cases.
+     */
+    code?: string;
     /**
      * Source-specific configuration.
      *
@@ -717,11 +682,21 @@ interface SourceReference {
      *
      * @remarks
      * The primary source's ELB function is returned by `startFlow()`.
-     * Only one source should be marked as primary per environment.
+     * Only one source should be marked as primary per flow.
      *
      * @default false
      */
     primary?: boolean;
+    /**
+     * Source-level variables (highest priority in cascade).
+     * Overrides flow and setup variables.
+     */
+    variables?: Variables;
+    /**
+     * Source-level definitions (highest priority in cascade).
+     * Overrides flow and setup definitions.
+     */
+    definitions?: Definitions;
 }
 /**
  * Destination reference with inline package syntax.
@@ -741,6 +716,14 @@ interface DestinationReference {
      * "package": "@walkeros/web-destination-gtag@2.0.0"
      */
     package: string;
+    /**
+     * Resolved import variable name.
+     *
+     * @remarks
+     * Auto-resolved from packages[package].imports[0] during getFlowConfig().
+     * Can also be provided explicitly for advanced use cases.
+     */
+    code?: string;
     /**
      * Destination-specific configuration.
      *
@@ -782,23 +765,29 @@ interface DestinationReference {
      * Merged with default destination environment.
      */
     env?: unknown;
+    /**
+     * Destination-level variables (highest priority in cascade).
+     * Overrides flow and setup variables.
+     */
+    variables?: Variables;
+    /**
+     * Destination-level definitions (highest priority in cascade).
+     * Overrides flow and setup definitions.
+     */
+    definitions?: Definitions;
 }
 
+type flow_Definitions = Definitions;
 type flow_DestinationReference = DestinationReference;
+type flow_Packages = Packages;
 type flow_Primitive = Primitive;
+type flow_Server = Server;
 type flow_Setup = Setup;
 type flow_SourceReference = SourceReference;
+type flow_Variables = Variables;
+type flow_Web = Web;
 declare namespace flow {
-  export type { Config$3 as Config, flow_DestinationReference as DestinationReference, flow_Primitive as Primitive, flow_Setup as Setup, flow_SourceReference as SourceReference };
-}
-
-type Error = (error: unknown, state?: unknown) => void;
-type Log = (message: string, verbose?: boolean) => void;
-
-type handler_Error = Error;
-type handler_Log = Log;
-declare namespace handler {
-  export type { handler_Error as Error, handler_Log as Log };
+  export type { Config$4 as Config, flow_Definitions as Definitions, flow_DestinationReference as DestinationReference, flow_Packages as Packages, flow_Primitive as Primitive, flow_Server as Server, flow_Setup as Setup, flow_SourceReference as SourceReference, flow_Variables as Variables, flow_Web as Web };
 }
 
 type AnyFunction$1<P extends unknown[] = never[], R = unknown> = (...args: P) => R;
@@ -817,6 +806,121 @@ declare namespace hooks {
   export type { AnyFunction$1 as AnyFunction, hooks_Functions as Functions, hooks_HookFn as HookFn };
 }
 
+/**
+ * Log levels from most to least severe
+ */
+declare enum Level {
+    ERROR = 0,
+    INFO = 1,
+    DEBUG = 2
+}
+/**
+ * Normalized error context extracted from Error objects
+ */
+interface ErrorContext {
+    message: string;
+    name: string;
+    stack?: string;
+    cause?: unknown;
+}
+/**
+ * Context passed to log handlers
+ * If an Error was passed, it's normalized into the error property
+ */
+interface LogContext {
+    [key: string]: unknown;
+    error?: ErrorContext;
+}
+/**
+ * Log message function signature
+ * Accepts string or Error as message, with optional context
+ */
+type LogFn = (message: string | Error, context?: unknown | Error) => void;
+/**
+ * Throw function signature - logs error then throws
+ * Returns never as it always throws
+ */
+type ThrowFn = (message: string | Error, context?: unknown) => never;
+/**
+ * Default handler function (passed to custom handlers for chaining)
+ */
+type DefaultHandler = (level: Level, message: string, context: LogContext, scope: string[]) => void;
+/**
+ * Custom log handler function
+ * Receives originalHandler to allow middleware-style chaining
+ */
+type Handler = (level: Level, message: string, context: LogContext, scope: string[], originalHandler: DefaultHandler) => void;
+/**
+ * Logger instance with scoping support
+ * All logs automatically include trace path from scoping
+ */
+interface Instance$1 {
+    /**
+     * Log an error message (always visible unless silenced)
+     */
+    error: LogFn;
+    /**
+     * Log an informational message
+     */
+    info: LogFn;
+    /**
+     * Log a debug message
+     */
+    debug: LogFn;
+    /**
+     * Log an error message and throw an Error
+     * Combines logging and throwing in one call
+     */
+    throw: ThrowFn;
+    /**
+     * Create a scoped child logger with automatic trace path
+     * @param name - Scope name (e.g., destination type, destination key)
+     * @returns A new logger instance with the scope applied
+     */
+    scope: (name: string) => Instance$1;
+}
+/**
+ * Logger configuration options
+ */
+interface Config$3 {
+    /**
+     * Minimum log level to display
+     * @default Level.ERROR
+     */
+    level?: Level | keyof typeof Level;
+    /**
+     * Custom log handler function
+     * Receives originalHandler to preserve default behavior
+     */
+    handler?: Handler;
+}
+/**
+ * Internal config with resolved values and scope
+ */
+interface InternalConfig {
+    level: Level;
+    handler?: Handler;
+    scope: string[];
+}
+/**
+ * Logger factory function type
+ */
+type Factory = (config?: Config$3) => Instance$1;
+
+type logger_DefaultHandler = DefaultHandler;
+type logger_ErrorContext = ErrorContext;
+type logger_Factory = Factory;
+type logger_Handler = Handler;
+type logger_InternalConfig = InternalConfig;
+type logger_Level = Level;
+declare const logger_Level: typeof Level;
+type logger_LogContext = LogContext;
+type logger_LogFn = LogFn;
+type logger_ThrowFn = ThrowFn;
+declare namespace logger {
+  export { type Config$3 as Config, type logger_DefaultHandler as DefaultHandler, type logger_ErrorContext as ErrorContext, type logger_Factory as Factory, type logger_Handler as Handler, type Instance$1 as Instance, type logger_InternalConfig as InternalConfig, logger_Level as Level, type logger_LogContext as LogContext, type logger_LogFn as LogFn, type logger_ThrowFn as ThrowFn };
+}
+
 /**
  * Shared mapping configuration interface.
  * Used by both Source.Config and Destination.Config.
@@ -835,7 +939,7 @@ interface Rules<T = Rule> {
 }
 interface Rule<Settings = unknown> {
     batch?: number;
-    batchFn?: (destination: Instance$1, collector: Instance$2) => void;
+    batchFn?: (destination: Instance$2, collector: Instance$3) => void;
     batched?: Batch<Settings>;
     condition?: Condition;
     consent?: Consent;
@@ -864,7 +968,7 @@ interface ValueConfig {
     validate?: Validate;
     value?: PropertyType;
 }
-type Condition = (value: DeepPartialEvent | unknown, mapping?: Value, collector?: Instance$2) => PromiseOrValue<boolean>;
+type Condition = (value: DeepPartialEvent | unknown, mapping?: Value, collector?: Instance$3) => PromiseOrValue<boolean>;
 type Fn = (value: DeepPartialEvent | unknown, mapping: Value, options: Options$1) => PromiseOrValue<Property | unknown>;
 type Loop = [Value, Value];
 type Map = {
@@ -872,7 +976,7 @@ type Map = {
 };
 interface Options$1 {
     consent?: Consent;
-    collector?: Instance$2;
+    collector?: Instance$3;
     props?: unknown;
 }
 type Validate = (value?: unknown) => PromiseOrValue<boolean>;
@@ -918,13 +1022,13 @@ type Options = ConsentConfig | ReadyConfig | RunConfig | SessionConfig;
 interface ConsentConfig {
     [key: string]: ConsentFn;
 }
-type ConsentFn = (collector: Instance$2, consent: Consent) => void;
+type ConsentFn = (collector: Instance$3, consent: Consent) => void;
 type ReadyConfig = ReadyFn;
-type ReadyFn = (collector: Instance$2) => void;
+type ReadyFn = (collector: Instance$3) => void;
 type RunConfig = RunFn;
-type RunFn = (collector: Instance$2) => void;
+type RunFn = (collector: Instance$3) => void;
 type SessionConfig = SessionFn;
-type SessionFn = (collector: Instance$2, session?: unknown) => void;
+type SessionFn = (collector: Instance$3, session?: unknown) => void;
 interface OnConfig {
     consent?: ConsentConfig[];
     ready?: ReadyConfig[];
@@ -1012,18 +1116,21 @@ interface BaseEnv {
     command: CommandFn;
     sources?: Sources;
     elb: Fn$1;
+    logger: Instance$1;
 }
 /**
  * Type bundle for source generics.
- * Groups Settings, Mapping, Push, and Env into a single type parameter.
+ * Groups Settings, Mapping, Push, Env, and InitSettings into a single type parameter.
  *
  * @template S - Settings configuration type
  * @template M - Mapping configuration type
  * @template P - Push function signature (flexible to support HTTP handlers, etc.)
  * @template E - Environment dependencies type
+ * @template I - InitSettings configuration type (user input)
  */
-interface Types<S = unknown, M = unknown, P = Fn$1, E = BaseEnv> {
+interface Types<S = unknown, M = unknown, P = Fn$1, E = BaseEnv, I = S> {
     settings: S;
+    initSettings: I;
     mapping: M;
     push: P;
     env: E;
@@ -1033,6 +1140,7 @@ interface Types<S = unknown, M = unknown, P = Fn$1, E = BaseEnv> {
  */
 type TypesGeneric = {
     settings: any;
+    initSettings: any;
     mapping: any;
     push: any;
     env: any;
@@ -1041,6 +1149,7 @@ type TypesGeneric = {
  * Type extractors for consistent usage with Types bundle
  */
 type Settings<T extends TypesGeneric = Types> = T['settings'];
+type InitSettings<T extends TypesGeneric = Types> = T['initSettings'];
 type Mapping<T extends TypesGeneric = Types> = T['mapping'];
 type Push<T extends TypesGeneric = Types> = T['push'];
 type Env<T extends TypesGeneric = Types> = T['env'];
@@ -1049,10 +1158,10 @@ type Env<T extends TypesGeneric = Types> = T['env'];
  */
 type TypesOf<I> = I extends Instance<infer T> ? T : never;
 interface Config<T extends TypesGeneric = Types> extends Config$2<Mapping<T>> {
-    settings?: Settings<T>;
+    settings?: InitSettings<T>;
     env?: Env<T>;
     id?: string;
-    onError?: Error;
+    logger?: Config$3;
     disabled?: boolean;
     primary?: boolean;
 }
@@ -1083,6 +1192,7 @@ type source_BaseEnv = BaseEnv;
 type source_Config<T extends TypesGeneric = Types> = Config<T>;
 type source_Env<T extends TypesGeneric = Types> = Env<T>;
 type source_Init<T extends TypesGeneric = Types> = Init<T>;
+type source_InitSettings<T extends TypesGeneric = Types> = InitSettings<T>;
 type source_InitSource<T extends TypesGeneric = Types> = InitSource<T>;
 type source_InitSources = InitSources;
 type source_Instance<T extends TypesGeneric = Types> = Instance<T>;
@@ -1090,11 +1200,11 @@ type source_Mapping<T extends TypesGeneric = Types> = Mapping<T>;
 type source_PartialConfig<T extends TypesGeneric = Types> = PartialConfig<T>;
 type source_Push<T extends TypesGeneric = Types> = Push<T>;
 type source_Settings<T extends TypesGeneric = Types> = Settings<T>;
-type source_Types<S = unknown, M = unknown, P = Fn$1, E = BaseEnv> = Types<S, M, P, E>;
+type source_Types<S = unknown, M = unknown, P = Fn$1, E = BaseEnv, I = S> = Types<S, M, P, E, I>;
 type source_TypesGeneric = TypesGeneric;
 type source_TypesOf<I> = TypesOf<I>;
 declare namespace source {
-  export type { source_BaseEnv as BaseEnv, source_Config as Config, source_Env as Env, source_Init as Init, source_InitSource as InitSource, source_InitSources as InitSources, source_Instance as Instance, source_Mapping as Mapping, source_PartialConfig as PartialConfig, source_Push as Push, source_Settings as Settings, source_Types as Types, source_TypesGeneric as TypesGeneric, source_TypesOf as TypesOf };
+  export type { source_BaseEnv as BaseEnv, source_Config as Config, source_Env as Env, source_Init as Init, source_InitSettings as InitSettings, source_InitSource as InitSource, source_InitSources as InitSources, source_Instance as Instance, source_Mapping as Mapping, source_PartialConfig as PartialConfig, source_Push as Push, source_Settings as Settings, source_Types as Types, source_TypesGeneric as TypesGeneric, source_TypesOf as TypesOf };
 }
 
 type AnyObject<T = unknown> = Record<string, T>;
@@ -1241,6 +1351,53 @@ interface SendResponse {
  */
 declare function anonymizeIP(ip: string): string;
 
+/**
+ * Flow Configuration Utilities
+ *
+ * Functions for resolving and processing Flow configurations.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Get resolved flow configuration for a named flow.
+ *
+ * @param setup - The complete setup configuration
+ * @param flowName - Flow name (auto-selected if only one exists)
+ * @returns Resolved Config with variables/definitions interpolated and $refs resolved
+ * @throws Error if flow selection is required but not specified, or flow not found
+ *
+ * @example
+ * ```typescript
+ * import { getFlowConfig } from '@walkeros/core';
+ *
+ * const setup = JSON.parse(fs.readFileSync('walkeros.config.json', 'utf8'));
+ *
+ * // Auto-select if only one flow
+ * const config = getFlowConfig(setup);
+ *
+ * // Or specify flow
+ * const prodConfig = getFlowConfig(setup, 'production');
+ * ```
+ */
+declare function getFlowConfig(setup: Setup, flowName?: string): Config$4;
+/**
+ * Get platform from config (web or server).
+ *
+ * @param config - Flow configuration
+ * @returns "web" or "server"
+ * @throws Error if neither web nor server is present
+ *
+ * @example
+ * ```typescript
+ * import { getPlatform } from '@walkeros/core';
+ *
+ * const platform = getPlatform(config);
+ * // Returns "web" or "server"
+ * ```
+ */
+declare function getPlatform(config: Config$4): 'web' | 'server';
+
 /**
  * @interface Assign
  * @description Options for the assign function.
@@ -1335,7 +1492,7 @@ declare function getGrantedConsent(required: Consent | undefined, state?: Consen
  * }));
  * ```
  */
-declare function createDestination<I extends Instance$1>(baseDestination: I, config: Partial<Config$4<TypesOf$1<I>>>): I;
+declare function createDestination<I extends Instance$2>(baseDestination: I, config: Partial<Config$5<TypesOf$1<I>>>): I;
 
 /**
  * Creates a complete event with default values.
@@ -1469,6 +1626,36 @@ declare function isSameType<T>(variable: unknown, type: T): variable is typeof t
  */
 declare function isString(value: unknown): value is string;
 
+/**
+ * Create a logger instance
+ *
+ * @param config - Logger configuration
+ * @returns Logger instance with all log methods and scoping support
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const logger = createLogger({ level: 'DEBUG' });
+ * logger.info('Hello world');
+ *
+ * // With scoping
+ * const destLogger = logger.scope('gtag').scope('myInstance');
+ * destLogger.debug('Processing event'); // DEBUG [gtag:myInstance] Processing event
+ *
+ * // With custom handler
+ * const logger = createLogger({
+ *   handler: (level, message, context, scope, originalHandler) => {
+ *     // Custom logic (e.g., send to Sentry)
+ *     originalHandler(level, message, context, scope);
+ *   }
+ * });
+ * ```
+ *
+ * // TODO: Consider compile-time stripping of debug logs in production builds
+ * // e.g., if (__DEV__) { logger.debug(...) }
+ */
+declare function createLogger(config?: Config$3): Instance$1;
+
 /**
  * Gets the mapping for an event.
  *
@@ -1505,7 +1692,7 @@ declare function getMappingValue(value: DeepPartialEvent | unknown | undefined,
  * @param collector - Collector instance for context
  * @returns Object with transformed event, data, mapping rule, and ignore flag
  */
-declare function processEventMapping<T extends DeepPartialEvent | Event>(event: T, config: Config$2, collector: Instance$2): Promise<{
+declare function processEventMapping<T extends DeepPartialEvent | Event>(event: T, config: Config$2, collector: Instance$3): Promise<{
     event: T;
     data?: Property;
     mapping?: Rule;
@@ -1580,12 +1767,42 @@ declare function mockEnv<T extends object>(env: T, interceptor: InterceptorFn):
 declare function traverseEnv<T extends object>(env: T, replacer: (value: unknown, path: string[]) => unknown): T;
 
 /**
- * Logs a message to the console if verbose logging is enabled.
+ * Mock logger instance for testing
+ * Includes all logger methods as jest.fn() plus tracking of scoped loggers
+ * Extends Instance to ensure type compatibility
+ */
+interface MockLogger extends Instance$1 {
+    error: jest.Mock;
+    info: jest.Mock;
+    debug: jest.Mock;
+    throw: jest.Mock<never, [string | Error, unknown?]>;
+    scope: jest.Mock<MockLogger, [string]>;
+    /**
+     * Array of all scoped loggers created by this logger
+     * Useful for asserting on scoped logger calls in tests
+     */
+    scopedLoggers: MockLogger[];
+}
+/**
+ * Create a mock logger for testing
+ * All methods are jest.fn() that can be used for assertions
+ *
+ * @example
+ * ```typescript
+ * const mockLogger = createMockLogger();
  *
- * @param message The message to log.
- * @param verbose Whether to log the message.
+ * // Use in code under test
+ * someFunction(mockLogger);
+ *
+ * // Assert on calls
+ * expect(mockLogger.error).toHaveBeenCalledWith('error message');
+ *
+ * // Assert on scoped logger
+ * const scoped = mockLogger.scopedLoggers[0];
+ * expect(scoped.debug).toHaveBeenCalledWith('debug in scope');
+ * ```
  */
-declare function onLog(message: unknown, verbose?: boolean): void;
+declare function createMockLogger(): MockLogger;
 
 /**
  * Checks if a value is a valid property type.
@@ -1750,4 +1967,87 @@ declare function validateEvent(obj: unknown, customContracts?: Contracts): Event
  */
 declare function validateProperty(obj: AnyObject, key: string, value: unknown, schema: Property$1): Property | never;
 
-export { collector as Collector, Const, data as Data, destination as Destination, elb as Elb, flow as Flow, handler as Handler, hooks as Hooks, mapping as Mapping, type MarketingParameters, on as On, request as Request, schema as Schema, type SendDataValue, type SendHeaders, type SendResponse, source as Source, type StorageType, walkeros as WalkerOS, anonymizeIP, assign, castToProperty, castValue, clone, createDestination, createEvent, debounce, filterValues, getBrowser, getBrowserVersion, getByPath, getDeviceType, getEvent, getGrantedConsent, getHeaders, getId, getMappingEvent, getMappingValue, getMarketingParameters, getOS, getOSVersion, isArguments, isArray, isBoolean, isCommand, isDefined, isElementOrDocument, isFunction, isNumber, isObject, isPropertyType, isSameType, isString, mockEnv, onLog, parseUserAgent, processEventMapping, requestToData, requestToParameter, setByPath, throttle, throwError, transformData, traverseEnv, trim, tryCatch, tryCatchAsync, useHooks, validateEvent, validateProperty };
+/**
+ * Inline Code Wrapping Utilities
+ *
+ * Converts inline code strings to executable functions.
+ * Used for mapping properties: condition, fn, validate.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Wrap inline code string as Condition function.
+ *
+ * @param code - Inline code string
+ * @returns Condition function matching Mapping.Condition signature
+ *
+ * @remarks
+ * Available parameters in code:
+ * - `value` - The event or partial event being processed
+ * - `mapping` - Current mapping configuration
+ * - `collector` - Collector instance
+ *
+ * If code has no explicit return, it's auto-wrapped with `return`.
+ *
+ * @example
+ * ```typescript
+ * // One-liner (auto-wrapped)
+ * const fn = wrapCondition('value.data.total > 100');
+ * fn(event, mapping, collector); // returns boolean
+ *
+ * // Multi-statement (explicit return)
+ * const fn = wrapCondition('const threshold = 100; return value.data.total > threshold');
+ * ```
+ */
+declare function wrapCondition(code: string): Condition;
+/**
+ * Wrap inline code string as Fn function.
+ *
+ * @param code - Inline code string
+ * @returns Fn function matching Mapping.Fn signature
+ *
+ * @remarks
+ * Available parameters in code:
+ * - `value` - The event or partial event being processed
+ * - `mapping` - Current mapping configuration
+ * - `options` - Options object with consent and collector
+ *
+ * If code has no explicit return, it's auto-wrapped with `return`.
+ *
+ * @example
+ * ```typescript
+ * // One-liner (auto-wrapped)
+ * const fn = wrapFn('value.user.email.split("@")[1]');
+ * fn(event, mapping, options); // returns domain
+ *
+ * // Multi-statement (explicit return)
+ * const fn = wrapFn('const parts = value.user.email.split("@"); return parts[1].toUpperCase()');
+ * ```
+ */
+declare function wrapFn(code: string): Fn;
+/**
+ * Wrap inline code string as Validate function.
+ *
+ * @param code - Inline code string
+ * @returns Validate function matching Mapping.Validate signature
+ *
+ * @remarks
+ * Available parameters in code:
+ * - `value` - The current value being validated
+ *
+ * If code has no explicit return, it's auto-wrapped with `return`.
+ *
+ * @example
+ * ```typescript
+ * // One-liner (auto-wrapped)
+ * const fn = wrapValidate('value && value.length > 0');
+ * fn('hello'); // returns true
+ *
+ * // Multi-statement (explicit return)
+ * const fn = wrapValidate('if (!value) return false; return value.length > 0');
+ * ```
+ */
+declare function wrapValidate(code: string): Validate;
+
+export { collector as Collector, Const, data as Data, destination as Destination, elb as Elb, flow as Flow, hooks as Hooks, Level, logger as Logger, mapping as Mapping, type MarketingParameters, type MockLogger, on as On, request as Request, schema as Schema, type SendDataValue, type SendHeaders, type SendResponse, source as Source, type StorageType, walkeros as WalkerOS, anonymizeIP, assign, castToProperty, castValue, clone, createDestination, createEvent, createLogger, createMockLogger, debounce, filterValues, getBrowser, getBrowserVersion, getByPath, getDeviceType, getEvent, getFlowConfig, getGrantedConsent, getHeaders, getId, getMappingEvent, getMappingValue, getMarketingParameters, getOS, getOSVersion, getPlatform, isArguments, isArray, isBoolean, isCommand, isDefined, isElementOrDocument, isFunction, isNumber, isObject, isPropertyType, isSameType, isString, mockEnv, parseUserAgent, processEventMapping, requestToData, requestToParameter, setByPath, throttle, throwError, transformData, traverseEnv, trim, tryCatch, tryCatchAsync, useHooks, validateEvent, validateProperty, wrapCondition, wrapFn, wrapValidate };