@walkeros/core 3.2.0 → 3.3.0-next-1776113011459

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -27,6 +27,7 @@ declare namespace matcher {
27
27
  interface Config$8<T = unknown> {
28
28
  consent?: Consent;
29
29
  data?: Value | Values;
30
+ include?: string[];
30
31
  mapping?: Rules<Rule<T>>;
31
32
  policy?: Policy$1;
32
33
  }
@@ -44,7 +45,9 @@ interface Rule<Settings = unknown> {
44
45
  consent?: Consent;
45
46
  settings?: Settings;
46
47
  data?: Data$1;
48
+ include?: string[];
47
49
  ignore?: boolean;
50
+ skip?: boolean;
48
51
  name?: string;
49
52
  policy?: Policy$1;
50
53
  }
@@ -444,6 +447,8 @@ interface Config$6<T extends TypesGeneric$3 = Types$4> {
444
447
  settings?: InitSettings$3<T>;
445
448
  /** Global data transformation applied to all events; result passed as context.data to push. */
446
449
  data?: Value | Values;
450
+ /** Event sections to flatten into context.data. */
451
+ include?: string[];
447
452
  /** Runtime dependencies merged from code and config env; extensible per destination. */
448
453
  env?: Env$3<T>;
449
454
  /** Destination identifier; auto-generated if not provided. */
@@ -691,6 +696,36 @@ type Packages = Record<string, {
691
696
  imports?: string[];
692
697
  path?: string;
693
698
  }>;
699
+ /**
700
+ * Transitive dependency version pins for bundling.
701
+ *
702
+ * @remarks
703
+ * Maps package name → version spec. Applied during bundle package install
704
+ * to force transitive dependencies to a specific version. Useful for
705
+ * resolving conflicts between packages that depend on incompatible
706
+ * versions of a shared dependency.
707
+ *
708
+ * @example
709
+ * ```json
710
+ * {
711
+ * "@amplitude/analytics-types": "2.11.1"
712
+ * }
713
+ * ```
714
+ */
715
+ type Overrides = Record<string, string>;
716
+ /**
717
+ * Bundle configuration for a flow.
718
+ *
719
+ * @remarks
720
+ * Groups all build-time bundling concerns: NPM packages to include and
721
+ * transitive dependency overrides. Consumed by the CLI bundler.
722
+ */
723
+ interface Bundle {
724
+ /** NPM packages to bundle. */
725
+ packages?: Packages;
726
+ /** Transitive dependency version pins. */
727
+ overrides?: Overrides;
728
+ }
694
729
  /**
695
730
  * Web platform configuration.
696
731
  *
@@ -947,9 +982,12 @@ interface Settings$3 {
947
982
  */
948
983
  collector?: InitConfig;
949
984
  /**
950
- * NPM packages to bundle.
985
+ * Bundle configuration (packages to include, transitive overrides).
986
+ *
987
+ * @remarks
988
+ * Groups NPM `packages` and dependency `overrides` used at build time.
951
989
  */
952
- packages?: Packages;
990
+ bundle?: Bundle;
953
991
  /**
954
992
  * Flow-level variables.
955
993
  * Override Config.variables, overridden by source/destination variables.
@@ -961,10 +999,29 @@ interface Settings$3 {
961
999
  */
962
1000
  definitions?: Definitions;
963
1001
  }
1002
+ /**
1003
+ * Walker command names that a step example can invoke instead of pushing
1004
+ * its `in` as a regular event. Mirrors the `elb('walker <command>', ...)`
1005
+ * surface in `WalkerCommands` (see types/elb.ts).
1006
+ *
1007
+ * - `config` — update collector config (maps to `elb('walker config', in)`)
1008
+ * - `consent` — update consent state (maps to `elb('walker consent', in)`)
1009
+ * - `user` — update user identification (maps to `elb('walker user', in)`)
1010
+ * - `run` — fire run state (maps to `elb('walker run', in)`)
1011
+ *
1012
+ * Note: `walker destination`, `walker hook`, and `walker on` are
1013
+ * intentionally excluded — they configure wiring, not test data.
1014
+ */
1015
+ type StepCommand = 'config' | 'consent' | 'user' | 'run';
964
1016
  /**
965
1017
  * Named example pair for a step.
966
1018
  * `in` is the input to the step, `out` is the expected output.
967
1019
  * `out: false` indicates the step filters/drops this event.
1020
+ *
1021
+ * When `command` is set, the test runner invokes
1022
+ * `elb('walker <command>', in)` instead of pushing `in` as a regular event.
1023
+ * When `command` is absent (default), `in` is pushed as a normal event via
1024
+ * `elb(event)`.
968
1025
  */
969
1026
  interface StepExample {
970
1027
  description?: string;
@@ -978,6 +1035,12 @@ interface StepExample {
978
1035
  };
979
1036
  mapping?: unknown;
980
1037
  out?: unknown;
1038
+ /**
1039
+ * Invoke a walker command with `in` instead of pushing `in` as an event.
1040
+ * When set, the test runner calls `elb('walker <command>', in)`.
1041
+ * When absent (default), `in` is pushed as a regular event.
1042
+ */
1043
+ command?: StepCommand;
981
1044
  }
982
1045
  /**
983
1046
  * Named step examples keyed by scenario name.
@@ -1359,6 +1422,7 @@ interface DestinationReference {
1359
1422
  examples?: StepExamples;
1360
1423
  }
1361
1424
 
1425
+ type flow_Bundle = Bundle;
1362
1426
  type flow_Contract = Contract;
1363
1427
  type flow_ContractActions = ContractActions;
1364
1428
  type flow_ContractEntry = ContractEntry;
@@ -1367,10 +1431,12 @@ type flow_ContractSchema = ContractSchema;
1367
1431
  type flow_Definitions = Definitions;
1368
1432
  type flow_DestinationReference = DestinationReference;
1369
1433
  type flow_InlineCode = InlineCode;
1434
+ type flow_Overrides = Overrides;
1370
1435
  type flow_Packages = Packages;
1371
1436
  type flow_Primitive = Primitive;
1372
1437
  type flow_Server = Server;
1373
1438
  type flow_SourceReference = SourceReference;
1439
+ type flow_StepCommand = StepCommand;
1374
1440
  type flow_StepExample = StepExample;
1375
1441
  type flow_StepExamples = StepExamples;
1376
1442
  type flow_StoreReference = StoreReference;
@@ -1378,7 +1444,7 @@ type flow_TransformerReference = TransformerReference;
1378
1444
  type flow_Variables = Variables;
1379
1445
  type flow_Web = Web;
1380
1446
  declare namespace flow {
1381
- export type { Config$5 as Config, flow_Contract as Contract, flow_ContractActions as ContractActions, flow_ContractEntry as ContractEntry, flow_ContractEvents as ContractEvents, flow_ContractSchema as ContractSchema, flow_Definitions as Definitions, flow_DestinationReference as DestinationReference, flow_InlineCode as InlineCode, flow_Packages as Packages, flow_Primitive as Primitive, flow_Server as Server, Settings$3 as Settings, flow_SourceReference as SourceReference, flow_StepExample as StepExample, flow_StepExamples as StepExamples, flow_StoreReference as StoreReference, flow_TransformerReference as TransformerReference, flow_Variables as Variables, flow_Web as Web };
1447
+ export type { flow_Bundle as Bundle, Config$5 as Config, flow_Contract as Contract, flow_ContractActions as ContractActions, flow_ContractEntry as ContractEntry, flow_ContractEvents as ContractEvents, flow_ContractSchema as ContractSchema, flow_Definitions as Definitions, flow_DestinationReference as DestinationReference, flow_InlineCode as InlineCode, flow_Overrides as Overrides, flow_Packages as Packages, flow_Primitive as Primitive, flow_Server as Server, Settings$3 as Settings, flow_SourceReference as SourceReference, flow_StepCommand as StepCommand, flow_StepExample as StepExample, flow_StepExamples as StepExamples, flow_StoreReference as StoreReference, flow_TransformerReference as TransformerReference, flow_Variables as Variables, flow_Web as Web };
1382
1448
  }
1383
1449
 
1384
1450
  type AnyFunction$1<P extends unknown[] = never[], R = unknown> = (...args: P) => R;
@@ -2406,6 +2472,8 @@ declare function getByPath(event: unknown, key?: string, defaultValue?: unknown)
2406
2472
  */
2407
2473
  declare function setByPath<T = unknown>(obj: T, key: string, value: unknown): T;
2408
2474
 
2475
+ declare function flattenIncludeSections(event: DeepPartialEvent, sections: string[]): Record<string, unknown>;
2476
+
2409
2477
  /**
2410
2478
  * Casts a value to a specific type.
2411
2479
  *
@@ -2492,14 +2560,40 @@ declare function getId(length?: number): string;
2492
2560
  interface MarketingParameters {
2493
2561
  [key: string]: string;
2494
2562
  }
2563
+ /**
2564
+ * Click-ID registry entry — maps a URL parameter name to a canonical platform.
2565
+ *
2566
+ * Runtime shape only; the corresponding Zod schema lives in
2567
+ * `@walkeros/core/dev` (schemas/marketing.ts) for dev tooling that needs
2568
+ * validation or JSON Schema generation.
2569
+ */
2570
+ interface ClickIdEntry {
2571
+ param: string;
2572
+ platform: string;
2573
+ }
2574
+ /**
2575
+ * Default click-ID registry.
2576
+ *
2577
+ * Ordered by priority: when a URL contains multiple click IDs, the entry
2578
+ * appearing earlier wins as the resolved `clickId` / `platform`. All matched
2579
+ * raw values are still preserved on the result.
2580
+ *
2581
+ * Extend via the third argument to {@link getMarketingParameters} or the
2582
+ * `clickIds` field in the session source settings.
2583
+ */
2584
+ declare const defaultClickIds: ClickIdEntry[];
2495
2585
  /**
2496
2586
  * Extracts marketing parameters from a URL.
2497
2587
  *
2498
- * @param url - The URL to extract the parameters from.
2499
- * @param custom - Custom marketing parameters to extract.
2500
- * @returns The extracted marketing parameters.
2588
+ * - UTM and custom params are mapped to friendly names (`utm_source` → `source`).
2589
+ * - Known click IDs are detected case-insensitively; each raw value is stored
2590
+ * under its canonical lowercase param name.
2591
+ * - `clickId` and `platform` reference the highest-priority match (first entry
2592
+ * in the registry present in the URL).
2593
+ * - Custom `clickIds` override default platforms by `param` in place and
2594
+ * append new params at the end of the priority list.
2501
2595
  */
2502
- declare function getMarketingParameters(url: URL, custom?: MarketingParameters): Properties;
2596
+ declare function getMarketingParameters(url: URL, custom?: MarketingParameters, clickIds?: ClickIdEntry[]): Properties;
2503
2597
 
2504
2598
  /**
2505
2599
  * Creates a debounced function that delays invoking `fn` until after `wait`
@@ -2667,6 +2761,7 @@ declare function processEventMapping<T extends DeepPartialEvent | Event>(event:
2667
2761
  mapping?: Rule;
2668
2762
  mappingKey?: string;
2669
2763
  ignore: boolean;
2764
+ skip: boolean;
2670
2765
  }>;
2671
2766
 
2672
2767
  /**
@@ -3133,13 +3228,6 @@ declare function isRouteArray(next: Next): next is NextRule[];
3133
3228
  declare function compileNext(next: Next | undefined): CompiledNext | undefined;
3134
3229
  declare function resolveNext(compiled: CompiledNext | undefined, context?: Record<string, unknown>): string | string[] | undefined;
3135
3230
 
3136
- type PackageType = 'source' | 'destination' | 'transformer' | 'store';
3137
- interface PackageSchemas {
3138
- settings?: Record<string, unknown>;
3139
- [key: string]: unknown;
3140
- }
3141
- declare function mergeConfigSchema(type: PackageType, packageSchemas: PackageSchemas): Record<string, unknown>;
3142
-
3143
3231
  interface CompiledCacheRule {
3144
3232
  match: CompiledMatcher;
3145
3233
  key: string[];
@@ -3167,4 +3255,4 @@ declare function checkCache(compiled: CompiledCache, store: Instance$1, context:
3167
3255
  declare function storeCache(store: Instance$1, key: string, value: unknown, ttlSeconds: number): void;
3168
3256
  declare function applyUpdate(value: unknown, update: Record<string, unknown> | undefined, context: Record<string, unknown>): Promise<unknown>;
3169
3257
 
3170
- export { cache as Cache, type CacheResult, collector as Collector, type CompiledCache, type CompiledNext, type CompiledRoute, Const, context as Context, destination as Destination, ENV_MARKER_PREFIX, elb as Elb, type ExampleSummary, flow as Flow, hint as Hint, hooks as Hooks, type Ingest, type IngestMeta, Level, lifecycle as Lifecycle, logger as Logger, mapping as Mapping, type MarketingParameters, matcher as Matcher, type MockLogger, on as On, request as Request, type ResolveOptions, type RespondFn, type RespondOptions, type SendDataValue, type SendHeaders, type SendResponse, simulation as Simulation, source as Source, type StorageType, store as Store, transformer as Transformer, trigger as Trigger, walkeros as WalkerOS, type WalkerOSPackage, type WalkerOSPackageInfo, type WalkerOSPackageMeta, anonymizeIP, applyUpdate, assign, branch, buildCacheContext, castToProperty, castValue, checkCache, clone, compileCache, compileMatcher, compileNext, createDestination, createEvent, createIngest, createLogger, createMockContext, createMockLogger, createRespond, debounce, deepMerge, fetchPackage, fetchPackageSchema, filterValues, getBrowser, getBrowserVersion, getByPath, getDeviceType, getEvent, getFlowSettings, getGrantedConsent, getHeaders, getId, getMappingEvent, getMappingValue, getMarketingParameters, getOS, getOSVersion, getPlatform, isArguments, isArray, isBoolean, isCommand, isDefined, isElementOrDocument, isFunction, isNumber, isObject, isPropertyType, isRouteArray, isSameType, isString, mcpError, mcpResult, mergeConfigSchema, mergeContractSchemas, mockEnv, packageNameToVariable, parseUserAgent, processEventMapping, requestToData, requestToParameter, resolveContracts, resolveNext, setByPath, storeCache, throttle, throwError, transformData, traverseEnv, trim, tryCatch, tryCatchAsync, useHooks, walkPath, wrapCondition, wrapFn, wrapValidate };
3258
+ export { cache as Cache, type CacheResult, type ClickIdEntry, collector as Collector, type CompiledCache, type CompiledNext, type CompiledRoute, Const, context as Context, destination as Destination, ENV_MARKER_PREFIX, elb as Elb, type ExampleSummary, flow as Flow, hint as Hint, hooks as Hooks, type Ingest, type IngestMeta, Level, lifecycle as Lifecycle, logger as Logger, mapping as Mapping, type MarketingParameters, matcher as Matcher, type MockLogger, on as On, request as Request, type ResolveOptions, type RespondFn, type RespondOptions, type SendDataValue, type SendHeaders, type SendResponse, simulation as Simulation, source as Source, type StorageType, store as Store, transformer as Transformer, trigger as Trigger, walkeros as WalkerOS, type WalkerOSPackage, type WalkerOSPackageInfo, type WalkerOSPackageMeta, anonymizeIP, applyUpdate, assign, branch, buildCacheContext, castToProperty, castValue, checkCache, clone, compileCache, compileMatcher, compileNext, createDestination, createEvent, createIngest, createLogger, createMockContext, createMockLogger, createRespond, debounce, deepMerge, defaultClickIds, fetchPackage, fetchPackageSchema, filterValues, flattenIncludeSections, getBrowser, getBrowserVersion, getByPath, getDeviceType, getEvent, getFlowSettings, getGrantedConsent, getHeaders, getId, getMappingEvent, getMappingValue, getMarketingParameters, getOS, getOSVersion, getPlatform, isArguments, isArray, isBoolean, isCommand, isDefined, isElementOrDocument, isFunction, isNumber, isObject, isPropertyType, isRouteArray, isSameType, isString, mcpError, mcpResult, mergeContractSchemas, mockEnv, packageNameToVariable, parseUserAgent, processEventMapping, requestToData, requestToParameter, resolveContracts, resolveNext, setByPath, storeCache, throttle, throwError, transformData, traverseEnv, trim, tryCatch, tryCatchAsync, useHooks, walkPath, wrapCondition, wrapFn, wrapValidate };
package/dist/index.d.ts CHANGED
@@ -27,6 +27,7 @@ declare namespace matcher {
27
27
  interface Config$8<T = unknown> {
28
28
  consent?: Consent;
29
29
  data?: Value | Values;
30
+ include?: string[];
30
31
  mapping?: Rules<Rule<T>>;
31
32
  policy?: Policy$1;
32
33
  }
@@ -44,7 +45,9 @@ interface Rule<Settings = unknown> {
44
45
  consent?: Consent;
45
46
  settings?: Settings;
46
47
  data?: Data$1;
48
+ include?: string[];
47
49
  ignore?: boolean;
50
+ skip?: boolean;
48
51
  name?: string;
49
52
  policy?: Policy$1;
50
53
  }
@@ -444,6 +447,8 @@ interface Config$6<T extends TypesGeneric$3 = Types$4> {
444
447
  settings?: InitSettings$3<T>;
445
448
  /** Global data transformation applied to all events; result passed as context.data to push. */
446
449
  data?: Value | Values;
450
+ /** Event sections to flatten into context.data. */
451
+ include?: string[];
447
452
  /** Runtime dependencies merged from code and config env; extensible per destination. */
448
453
  env?: Env$3<T>;
449
454
  /** Destination identifier; auto-generated if not provided. */
@@ -691,6 +696,36 @@ type Packages = Record<string, {
691
696
  imports?: string[];
692
697
  path?: string;
693
698
  }>;
699
+ /**
700
+ * Transitive dependency version pins for bundling.
701
+ *
702
+ * @remarks
703
+ * Maps package name → version spec. Applied during bundle package install
704
+ * to force transitive dependencies to a specific version. Useful for
705
+ * resolving conflicts between packages that depend on incompatible
706
+ * versions of a shared dependency.
707
+ *
708
+ * @example
709
+ * ```json
710
+ * {
711
+ * "@amplitude/analytics-types": "2.11.1"
712
+ * }
713
+ * ```
714
+ */
715
+ type Overrides = Record<string, string>;
716
+ /**
717
+ * Bundle configuration for a flow.
718
+ *
719
+ * @remarks
720
+ * Groups all build-time bundling concerns: NPM packages to include and
721
+ * transitive dependency overrides. Consumed by the CLI bundler.
722
+ */
723
+ interface Bundle {
724
+ /** NPM packages to bundle. */
725
+ packages?: Packages;
726
+ /** Transitive dependency version pins. */
727
+ overrides?: Overrides;
728
+ }
694
729
  /**
695
730
  * Web platform configuration.
696
731
  *
@@ -947,9 +982,12 @@ interface Settings$3 {
947
982
  */
948
983
  collector?: InitConfig;
949
984
  /**
950
- * NPM packages to bundle.
985
+ * Bundle configuration (packages to include, transitive overrides).
986
+ *
987
+ * @remarks
988
+ * Groups NPM `packages` and dependency `overrides` used at build time.
951
989
  */
952
- packages?: Packages;
990
+ bundle?: Bundle;
953
991
  /**
954
992
  * Flow-level variables.
955
993
  * Override Config.variables, overridden by source/destination variables.
@@ -961,10 +999,29 @@ interface Settings$3 {
961
999
  */
962
1000
  definitions?: Definitions;
963
1001
  }
1002
+ /**
1003
+ * Walker command names that a step example can invoke instead of pushing
1004
+ * its `in` as a regular event. Mirrors the `elb('walker <command>', ...)`
1005
+ * surface in `WalkerCommands` (see types/elb.ts).
1006
+ *
1007
+ * - `config` — update collector config (maps to `elb('walker config', in)`)
1008
+ * - `consent` — update consent state (maps to `elb('walker consent', in)`)
1009
+ * - `user` — update user identification (maps to `elb('walker user', in)`)
1010
+ * - `run` — fire run state (maps to `elb('walker run', in)`)
1011
+ *
1012
+ * Note: `walker destination`, `walker hook`, and `walker on` are
1013
+ * intentionally excluded — they configure wiring, not test data.
1014
+ */
1015
+ type StepCommand = 'config' | 'consent' | 'user' | 'run';
964
1016
  /**
965
1017
  * Named example pair for a step.
966
1018
  * `in` is the input to the step, `out` is the expected output.
967
1019
  * `out: false` indicates the step filters/drops this event.
1020
+ *
1021
+ * When `command` is set, the test runner invokes
1022
+ * `elb('walker <command>', in)` instead of pushing `in` as a regular event.
1023
+ * When `command` is absent (default), `in` is pushed as a normal event via
1024
+ * `elb(event)`.
968
1025
  */
969
1026
  interface StepExample {
970
1027
  description?: string;
@@ -978,6 +1035,12 @@ interface StepExample {
978
1035
  };
979
1036
  mapping?: unknown;
980
1037
  out?: unknown;
1038
+ /**
1039
+ * Invoke a walker command with `in` instead of pushing `in` as an event.
1040
+ * When set, the test runner calls `elb('walker <command>', in)`.
1041
+ * When absent (default), `in` is pushed as a regular event.
1042
+ */
1043
+ command?: StepCommand;
981
1044
  }
982
1045
  /**
983
1046
  * Named step examples keyed by scenario name.
@@ -1359,6 +1422,7 @@ interface DestinationReference {
1359
1422
  examples?: StepExamples;
1360
1423
  }
1361
1424
 
1425
+ type flow_Bundle = Bundle;
1362
1426
  type flow_Contract = Contract;
1363
1427
  type flow_ContractActions = ContractActions;
1364
1428
  type flow_ContractEntry = ContractEntry;
@@ -1367,10 +1431,12 @@ type flow_ContractSchema = ContractSchema;
1367
1431
  type flow_Definitions = Definitions;
1368
1432
  type flow_DestinationReference = DestinationReference;
1369
1433
  type flow_InlineCode = InlineCode;
1434
+ type flow_Overrides = Overrides;
1370
1435
  type flow_Packages = Packages;
1371
1436
  type flow_Primitive = Primitive;
1372
1437
  type flow_Server = Server;
1373
1438
  type flow_SourceReference = SourceReference;
1439
+ type flow_StepCommand = StepCommand;
1374
1440
  type flow_StepExample = StepExample;
1375
1441
  type flow_StepExamples = StepExamples;
1376
1442
  type flow_StoreReference = StoreReference;
@@ -1378,7 +1444,7 @@ type flow_TransformerReference = TransformerReference;
1378
1444
  type flow_Variables = Variables;
1379
1445
  type flow_Web = Web;
1380
1446
  declare namespace flow {
1381
- export type { Config$5 as Config, flow_Contract as Contract, flow_ContractActions as ContractActions, flow_ContractEntry as ContractEntry, flow_ContractEvents as ContractEvents, flow_ContractSchema as ContractSchema, flow_Definitions as Definitions, flow_DestinationReference as DestinationReference, flow_InlineCode as InlineCode, flow_Packages as Packages, flow_Primitive as Primitive, flow_Server as Server, Settings$3 as Settings, flow_SourceReference as SourceReference, flow_StepExample as StepExample, flow_StepExamples as StepExamples, flow_StoreReference as StoreReference, flow_TransformerReference as TransformerReference, flow_Variables as Variables, flow_Web as Web };
1447
+ export type { flow_Bundle as Bundle, Config$5 as Config, flow_Contract as Contract, flow_ContractActions as ContractActions, flow_ContractEntry as ContractEntry, flow_ContractEvents as ContractEvents, flow_ContractSchema as ContractSchema, flow_Definitions as Definitions, flow_DestinationReference as DestinationReference, flow_InlineCode as InlineCode, flow_Overrides as Overrides, flow_Packages as Packages, flow_Primitive as Primitive, flow_Server as Server, Settings$3 as Settings, flow_SourceReference as SourceReference, flow_StepCommand as StepCommand, flow_StepExample as StepExample, flow_StepExamples as StepExamples, flow_StoreReference as StoreReference, flow_TransformerReference as TransformerReference, flow_Variables as Variables, flow_Web as Web };
1382
1448
  }
1383
1449
 
1384
1450
  type AnyFunction$1<P extends unknown[] = never[], R = unknown> = (...args: P) => R;
@@ -2406,6 +2472,8 @@ declare function getByPath(event: unknown, key?: string, defaultValue?: unknown)
2406
2472
  */
2407
2473
  declare function setByPath<T = unknown>(obj: T, key: string, value: unknown): T;
2408
2474
 
2475
+ declare function flattenIncludeSections(event: DeepPartialEvent, sections: string[]): Record<string, unknown>;
2476
+
2409
2477
  /**
2410
2478
  * Casts a value to a specific type.
2411
2479
  *
@@ -2492,14 +2560,40 @@ declare function getId(length?: number): string;
2492
2560
  interface MarketingParameters {
2493
2561
  [key: string]: string;
2494
2562
  }
2563
+ /**
2564
+ * Click-ID registry entry — maps a URL parameter name to a canonical platform.
2565
+ *
2566
+ * Runtime shape only; the corresponding Zod schema lives in
2567
+ * `@walkeros/core/dev` (schemas/marketing.ts) for dev tooling that needs
2568
+ * validation or JSON Schema generation.
2569
+ */
2570
+ interface ClickIdEntry {
2571
+ param: string;
2572
+ platform: string;
2573
+ }
2574
+ /**
2575
+ * Default click-ID registry.
2576
+ *
2577
+ * Ordered by priority: when a URL contains multiple click IDs, the entry
2578
+ * appearing earlier wins as the resolved `clickId` / `platform`. All matched
2579
+ * raw values are still preserved on the result.
2580
+ *
2581
+ * Extend via the third argument to {@link getMarketingParameters} or the
2582
+ * `clickIds` field in the session source settings.
2583
+ */
2584
+ declare const defaultClickIds: ClickIdEntry[];
2495
2585
  /**
2496
2586
  * Extracts marketing parameters from a URL.
2497
2587
  *
2498
- * @param url - The URL to extract the parameters from.
2499
- * @param custom - Custom marketing parameters to extract.
2500
- * @returns The extracted marketing parameters.
2588
+ * - UTM and custom params are mapped to friendly names (`utm_source` → `source`).
2589
+ * - Known click IDs are detected case-insensitively; each raw value is stored
2590
+ * under its canonical lowercase param name.
2591
+ * - `clickId` and `platform` reference the highest-priority match (first entry
2592
+ * in the registry present in the URL).
2593
+ * - Custom `clickIds` override default platforms by `param` in place and
2594
+ * append new params at the end of the priority list.
2501
2595
  */
2502
- declare function getMarketingParameters(url: URL, custom?: MarketingParameters): Properties;
2596
+ declare function getMarketingParameters(url: URL, custom?: MarketingParameters, clickIds?: ClickIdEntry[]): Properties;
2503
2597
 
2504
2598
  /**
2505
2599
  * Creates a debounced function that delays invoking `fn` until after `wait`
@@ -2667,6 +2761,7 @@ declare function processEventMapping<T extends DeepPartialEvent | Event>(event:
2667
2761
  mapping?: Rule;
2668
2762
  mappingKey?: string;
2669
2763
  ignore: boolean;
2764
+ skip: boolean;
2670
2765
  }>;
2671
2766
 
2672
2767
  /**
@@ -3133,13 +3228,6 @@ declare function isRouteArray(next: Next): next is NextRule[];
3133
3228
  declare function compileNext(next: Next | undefined): CompiledNext | undefined;
3134
3229
  declare function resolveNext(compiled: CompiledNext | undefined, context?: Record<string, unknown>): string | string[] | undefined;
3135
3230
 
3136
- type PackageType = 'source' | 'destination' | 'transformer' | 'store';
3137
- interface PackageSchemas {
3138
- settings?: Record<string, unknown>;
3139
- [key: string]: unknown;
3140
- }
3141
- declare function mergeConfigSchema(type: PackageType, packageSchemas: PackageSchemas): Record<string, unknown>;
3142
-
3143
3231
  interface CompiledCacheRule {
3144
3232
  match: CompiledMatcher;
3145
3233
  key: string[];
@@ -3167,4 +3255,4 @@ declare function checkCache(compiled: CompiledCache, store: Instance$1, context:
3167
3255
  declare function storeCache(store: Instance$1, key: string, value: unknown, ttlSeconds: number): void;
3168
3256
  declare function applyUpdate(value: unknown, update: Record<string, unknown> | undefined, context: Record<string, unknown>): Promise<unknown>;
3169
3257
 
3170
- export { cache as Cache, type CacheResult, collector as Collector, type CompiledCache, type CompiledNext, type CompiledRoute, Const, context as Context, destination as Destination, ENV_MARKER_PREFIX, elb as Elb, type ExampleSummary, flow as Flow, hint as Hint, hooks as Hooks, type Ingest, type IngestMeta, Level, lifecycle as Lifecycle, logger as Logger, mapping as Mapping, type MarketingParameters, matcher as Matcher, type MockLogger, on as On, request as Request, type ResolveOptions, type RespondFn, type RespondOptions, type SendDataValue, type SendHeaders, type SendResponse, simulation as Simulation, source as Source, type StorageType, store as Store, transformer as Transformer, trigger as Trigger, walkeros as WalkerOS, type WalkerOSPackage, type WalkerOSPackageInfo, type WalkerOSPackageMeta, anonymizeIP, applyUpdate, assign, branch, buildCacheContext, castToProperty, castValue, checkCache, clone, compileCache, compileMatcher, compileNext, createDestination, createEvent, createIngest, createLogger, createMockContext, createMockLogger, createRespond, debounce, deepMerge, fetchPackage, fetchPackageSchema, filterValues, getBrowser, getBrowserVersion, getByPath, getDeviceType, getEvent, getFlowSettings, getGrantedConsent, getHeaders, getId, getMappingEvent, getMappingValue, getMarketingParameters, getOS, getOSVersion, getPlatform, isArguments, isArray, isBoolean, isCommand, isDefined, isElementOrDocument, isFunction, isNumber, isObject, isPropertyType, isRouteArray, isSameType, isString, mcpError, mcpResult, mergeConfigSchema, mergeContractSchemas, mockEnv, packageNameToVariable, parseUserAgent, processEventMapping, requestToData, requestToParameter, resolveContracts, resolveNext, setByPath, storeCache, throttle, throwError, transformData, traverseEnv, trim, tryCatch, tryCatchAsync, useHooks, walkPath, wrapCondition, wrapFn, wrapValidate };
3258
+ export { cache as Cache, type CacheResult, type ClickIdEntry, collector as Collector, type CompiledCache, type CompiledNext, type CompiledRoute, Const, context as Context, destination as Destination, ENV_MARKER_PREFIX, elb as Elb, type ExampleSummary, flow as Flow, hint as Hint, hooks as Hooks, type Ingest, type IngestMeta, Level, lifecycle as Lifecycle, logger as Logger, mapping as Mapping, type MarketingParameters, matcher as Matcher, type MockLogger, on as On, request as Request, type ResolveOptions, type RespondFn, type RespondOptions, type SendDataValue, type SendHeaders, type SendResponse, simulation as Simulation, source as Source, type StorageType, store as Store, transformer as Transformer, trigger as Trigger, walkeros as WalkerOS, type WalkerOSPackage, type WalkerOSPackageInfo, type WalkerOSPackageMeta, anonymizeIP, applyUpdate, assign, branch, buildCacheContext, castToProperty, castValue, checkCache, clone, compileCache, compileMatcher, compileNext, createDestination, createEvent, createIngest, createLogger, createMockContext, createMockLogger, createRespond, debounce, deepMerge, defaultClickIds, fetchPackage, fetchPackageSchema, filterValues, flattenIncludeSections, getBrowser, getBrowserVersion, getByPath, getDeviceType, getEvent, getFlowSettings, getGrantedConsent, getHeaders, getId, getMappingEvent, getMappingValue, getMarketingParameters, getOS, getOSVersion, getPlatform, isArguments, isArray, isBoolean, isCommand, isDefined, isElementOrDocument, isFunction, isNumber, isObject, isPropertyType, isRouteArray, isSameType, isString, mcpError, mcpResult, mergeContractSchemas, mockEnv, packageNameToVariable, parseUserAgent, processEventMapping, requestToData, requestToParameter, resolveContracts, resolveNext, setByPath, storeCache, throttle, throwError, transformData, traverseEnv, trim, tryCatch, tryCatchAsync, useHooks, walkPath, wrapCondition, wrapFn, wrapValidate };