@walkeros/core 0.6.0 → 0.8.0

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
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Core collector configuration interface
3
3
  */
4
- interface Config$6 {
4
+ interface Config$7 {
5
5
  /** Whether to run collector automatically */
6
6
  run?: boolean;
7
7
  /** Version for event tagging */
@@ -11,12 +11,12 @@ interface Config$6 {
11
11
  /** Static session data even on a new run */
12
12
  sessionStatic: Partial<SessionData>;
13
13
  /** Logger configuration */
14
- logger?: Config$3;
14
+ logger?: Config$4;
15
15
  }
16
16
  /**
17
17
  * Initialization configuration that extends Config with initial state
18
18
  */
19
- interface InitConfig extends Partial<Config$6> {
19
+ interface InitConfig extends Partial<Config$7> {
20
20
  /** Initial consent state */
21
21
  consent?: Consent;
22
22
  /** Initial user data */
@@ -27,6 +27,8 @@ interface InitConfig extends Partial<Config$6> {
27
27
  sources?: InitSources;
28
28
  /** Destination configurations */
29
29
  destinations?: InitDestinations;
30
+ /** Transformer configurations */
31
+ transformers?: InitTransformers;
30
32
  /** Initial custom properties */
31
33
  custom?: Properties;
32
34
  }
@@ -46,30 +48,46 @@ interface Sources {
46
48
  [id: string]: Instance;
47
49
  }
48
50
  interface Destinations$1 {
49
- [id: string]: Instance$2;
51
+ [id: string]: Instance$3;
52
+ }
53
+ interface Transformers$1 {
54
+ [id: string]: Instance$1;
55
+ }
56
+ /**
57
+ * Resolved transformer chains for a flow.
58
+ */
59
+ interface TransformerChain {
60
+ /** Ordered transformer IDs to run before collector (from source.next) */
61
+ pre: string[];
62
+ /** Per-destination transformer chains (from destination.before) */
63
+ post: Record<string, string[]>;
50
64
  }
51
65
  type CommandType = 'action' | 'config' | 'consent' | 'context' | 'destination' | 'elb' | 'globals' | 'hook' | 'init' | 'link' | 'run' | 'user' | 'walker' | string;
52
66
  /**
53
- * Context passed to collector.push for source mapping
67
+ * Options passed to collector.push() from sources.
68
+ * NOT a Context - just push metadata.
54
69
  */
55
- interface PushContext$1 {
56
- mapping?: Config$2;
70
+ interface PushOptions {
71
+ id?: string;
72
+ ingest?: unknown;
73
+ mapping?: Config$3;
74
+ preChain?: string[];
57
75
  }
58
76
  /**
59
77
  * Push function signature - handles events only
60
78
  */
61
79
  interface PushFn$1 {
62
- (event: DeepPartialEvent, context?: PushContext$1): Promise<PushResult>;
80
+ (event: DeepPartialEvent, options?: PushOptions): Promise<PushResult>;
63
81
  }
64
82
  /**
65
83
  * Command function signature - handles walker commands only
66
84
  */
67
85
  interface CommandFn {
68
- (command: 'config', config: Partial<Config$6>): Promise<PushResult>;
86
+ (command: 'config', config: Partial<Config$7>): Promise<PushResult>;
69
87
  (command: 'consent', consent: Consent): Promise<PushResult>;
70
- <T extends Types$2>(command: 'destination', destination: Init$1<T> | Instance$2<T>, config?: Config$5<T>): Promise<PushResult>;
88
+ <T extends Types$3>(command: 'destination', destination: Init$2<T> | Instance$3<T>, config?: Config$6<T>): Promise<PushResult>;
71
89
  <K extends keyof Functions>(command: 'hook', name: K, hookFn: Functions[K]): Promise<PushResult>;
72
- (command: 'on', type: Types$1, rules: SingleOrArray<Options>): Promise<PushResult>;
90
+ (command: 'on', type: Types$2, rules: SingleOrArray<Options>): Promise<PushResult>;
73
91
  (command: 'user', user: User): Promise<PushResult>;
74
92
  (command: 'run', runState?: {
75
93
  consent?: Consent;
@@ -79,20 +97,22 @@ interface CommandFn {
79
97
  }): Promise<PushResult>;
80
98
  (command: string, data?: unknown, options?: unknown): Promise<PushResult>;
81
99
  }
82
- interface Instance$3 {
100
+ interface Instance$4 {
83
101
  push: PushFn$1;
84
102
  command: CommandFn;
85
103
  allowed: boolean;
86
- config: Config$6;
104
+ config: Config$7;
87
105
  consent: Consent;
88
106
  count: number;
89
107
  custom: Properties;
90
108
  sources: Sources;
91
109
  destinations: Destinations$1;
110
+ transformers: Transformers$1;
111
+ transformerChain: TransformerChain;
92
112
  globals: Properties;
93
113
  group: string;
94
114
  hooks: Functions;
95
- logger: Instance$1;
115
+ logger: Instance$2;
96
116
  on: OnConfig;
97
117
  queue: Events;
98
118
  round: number;
@@ -105,10 +125,28 @@ interface Instance$3 {
105
125
  type collector_CommandFn = CommandFn;
106
126
  type collector_CommandType = CommandType;
107
127
  type collector_InitConfig = InitConfig;
128
+ type collector_PushOptions = PushOptions;
108
129
  type collector_SessionData = SessionData;
109
130
  type collector_Sources = Sources;
131
+ type collector_TransformerChain = TransformerChain;
110
132
  declare namespace collector {
111
- 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 };
133
+ export type { collector_CommandFn as CommandFn, collector_CommandType as CommandType, Config$7 as Config, Destinations$1 as Destinations, collector_InitConfig as InitConfig, Instance$4 as Instance, PushFn$1 as PushFn, collector_PushOptions as PushOptions, collector_SessionData as SessionData, collector_Sources as Sources, collector_TransformerChain as TransformerChain, Transformers$1 as Transformers };
134
+ }
135
+
136
+ /**
137
+ * Base context interface for walkerOS stages.
138
+ * Sources, Transformers, and Destinations extend this.
139
+ */
140
+ interface Base<C = unknown, E = unknown> {
141
+ collector: Instance$4;
142
+ logger: Instance$2;
143
+ config: C;
144
+ env: E;
145
+ }
146
+
147
+ type context_Base<C = unknown, E = unknown> = Base<C, E>;
148
+ declare namespace context {
149
+ export type { context_Base as Base };
112
150
  }
113
151
 
114
152
  interface Contract$1 {
@@ -121,7 +159,7 @@ interface Globals {
121
159
  [name: string]: Global;
122
160
  }
123
161
  interface Contexts {
124
- [name: string]: Context$3;
162
+ [name: string]: Context$5;
125
163
  }
126
164
  interface Entities$1 {
127
165
  [name: string]: Entity$1;
@@ -131,7 +169,7 @@ interface Properties$2 {
131
169
  }
132
170
  interface Global extends Property$2 {
133
171
  }
134
- interface Context$3 extends Property$2 {
172
+ interface Context$5 extends Property$2 {
135
173
  }
136
174
  interface Entity$1 {
137
175
  data: Properties$2;
@@ -160,7 +198,7 @@ type data_Globals = Globals;
160
198
  type data_PropertyValues = PropertyValues;
161
199
  type data_Trigger = Trigger;
162
200
  declare namespace data {
163
- export type { data_Action as Action, data_Actions as Actions, Context$3 as Context, data_Contexts as Contexts, Contract$1 as Contract, Entities$1 as Entities, Entity$1 as Entity, data_Global as Global, data_Globals as Globals, Properties$2 as Properties, Property$2 as Property, PropertyType$1 as PropertyType, data_PropertyValues as PropertyValues, data_Trigger as Trigger };
201
+ export type { data_Action as Action, data_Actions as Actions, Context$5 as Context, data_Contexts as Contexts, Contract$1 as Contract, Entities$1 as Entities, Entity$1 as Entity, data_Global as Global, data_Globals as Globals, Properties$2 as Properties, Property$2 as Property, PropertyType$1 as PropertyType, data_PropertyValues as PropertyValues, data_Trigger as Trigger };
164
202
  }
165
203
 
166
204
  /**
@@ -170,7 +208,7 @@ declare namespace data {
170
208
  * their runtime environment requirements. Platform-specific extensions
171
209
  * should extend this interface.
172
210
  */
173
- interface BaseEnv$1 {
211
+ interface BaseEnv$2 {
174
212
  /**
175
213
  * Generic global properties that destinations may require
176
214
  * Platform-specific implementations can extend this interface
@@ -181,7 +219,7 @@ interface BaseEnv$1 {
181
219
  * Type bundle for destination generics.
182
220
  * Groups Settings, InitSettings, Mapping, and Env into a single type parameter.
183
221
  */
184
- interface Types$2<S = unknown, M = unknown, E = BaseEnv$1, I = S> {
222
+ interface Types$3<S = unknown, M = unknown, E = BaseEnv$2, I = S> {
185
223
  settings: S;
186
224
  initSettings: I;
187
225
  mapping: M;
@@ -190,7 +228,7 @@ interface Types$2<S = unknown, M = unknown, E = BaseEnv$1, I = S> {
190
228
  /**
191
229
  * Generic constraint for Types - ensures T has required properties for indexed access
192
230
  */
193
- type TypesGeneric$1 = {
231
+ type TypesGeneric$2 = {
194
232
  settings: any;
195
233
  initSettings: any;
196
234
  mapping: any;
@@ -199,78 +237,74 @@ type TypesGeneric$1 = {
199
237
  /**
200
238
  * Type extractors for consistent usage with Types bundle
201
239
  */
202
- type Settings$1<T extends TypesGeneric$1 = Types$2> = T['settings'];
203
- type InitSettings$1<T extends TypesGeneric$1 = Types$2> = T['initSettings'];
204
- type Mapping$1<T extends TypesGeneric$1 = Types$2> = T['mapping'];
205
- type Env$1<T extends TypesGeneric$1 = Types$2> = T['env'];
240
+ type Settings$2<T extends TypesGeneric$2 = Types$3> = T['settings'];
241
+ type InitSettings$2<T extends TypesGeneric$2 = Types$3> = T['initSettings'];
242
+ type Mapping$1<T extends TypesGeneric$2 = Types$3> = T['mapping'];
243
+ type Env$2<T extends TypesGeneric$2 = Types$3> = T['env'];
206
244
  /**
207
245
  * Inference helper: Extract Types from Instance
208
246
  */
209
- type TypesOf$1<I> = I extends Instance$2<infer T> ? T : never;
210
- interface Instance$2<T extends TypesGeneric$1 = Types$2> {
211
- config: Config$5<T>;
247
+ type TypesOf$2<I> = I extends Instance$3<infer T> ? T : never;
248
+ interface Instance$3<T extends TypesGeneric$2 = Types$3> {
249
+ config: Config$6<T>;
212
250
  queue?: Events;
213
251
  dlq?: DLQ;
214
252
  batches?: BatchRegistry<Mapping$1<T>>;
215
253
  type?: string;
216
- env?: Env$1<T>;
217
- init?: InitFn<T>;
254
+ env?: Env$2<T>;
255
+ init?: InitFn$1<T>;
218
256
  push: PushFn<T>;
219
257
  pushBatch?: PushBatchFn<T>;
220
258
  on?: OnFn;
221
259
  }
222
- interface Config$5<T extends TypesGeneric$1 = Types$2> {
260
+ interface Config$6<T extends TypesGeneric$2 = Types$3> {
223
261
  consent?: Consent;
224
- settings?: InitSettings$1<T>;
262
+ settings?: InitSettings$2<T>;
225
263
  data?: Value | Values;
226
- env?: Env$1<T>;
264
+ env?: Env$2<T>;
227
265
  id?: string;
228
266
  init?: boolean;
229
267
  loadScript?: boolean;
230
- logger?: Config$3;
268
+ logger?: Config$4;
231
269
  mapping?: Rules<Rule<Mapping$1<T>>>;
232
270
  policy?: Policy$1;
233
271
  queue?: boolean;
234
272
  }
235
- 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>>>;
273
+ type PartialConfig$1<T extends TypesGeneric$2 = Types$3> = Config$6<Types$3<Partial<Settings$2<T>> | Settings$2<T>, Partial<Mapping$1<T>> | Mapping$1<T>, Env$2<T>>>;
236
274
  interface Policy$1 {
237
275
  [key: string]: Value;
238
276
  }
239
- type Code<T extends TypesGeneric$1 = Types$2> = Instance$2<T> | true;
240
- type Init$1<T extends TypesGeneric$1 = Types$2> = {
277
+ type Code<T extends TypesGeneric$2 = Types$3> = Instance$3<T> | true;
278
+ type Init$2<T extends TypesGeneric$2 = Types$3> = {
241
279
  code: Code<T>;
242
- config?: Partial<Config$5<T>>;
243
- env?: Partial<Env$1<T>>;
280
+ config?: Partial<Config$6<T>>;
281
+ env?: Partial<Env$2<T>>;
244
282
  };
245
283
  interface InitDestinations {
246
- [key: string]: Init$1<any>;
284
+ [key: string]: Init$2<any>;
247
285
  }
248
286
  interface Destinations {
249
- [key: string]: Instance$2;
250
- }
251
- interface Context$2<T extends TypesGeneric$1 = Types$2> {
252
- collector: Instance$3;
253
- config: Config$5<T>;
254
- data?: Data$1;
255
- env: Env$1<T>;
256
- logger: Instance$1;
287
+ [key: string]: Instance$3;
257
288
  }
258
- interface InitContext<T extends TypesGeneric$1 = Types$2> {
259
- collector: Instance$3;
260
- config: Config$5<Types$2<Partial<Settings$1<T>>, Mapping$1<T>, Env$1<T>>>;
289
+ /**
290
+ * Context provided to destination functions.
291
+ * Extends base context with destination-specific properties.
292
+ */
293
+ interface Context$4<T extends TypesGeneric$2 = Types$3> extends Base<Config$6<T>, Env$2<T>> {
294
+ id: string;
261
295
  data?: Data$1;
262
- env: Env$1<T>;
263
- logger: Instance$1;
264
296
  }
265
- interface PushContext<T extends TypesGeneric$1 = Types$2> extends Context$2<T> {
266
- mapping?: Rule<Mapping$1<T>>;
297
+ interface PushContext<T extends TypesGeneric$2 = Types$3> extends Context$4<T> {
298
+ ingest?: unknown;
299
+ rule?: Rule<Mapping$1<T>>;
267
300
  }
268
- interface PushBatchContext<T extends TypesGeneric$1 = Types$2> extends Context$2<T> {
269
- mapping?: Rule<Mapping$1<T>>;
301
+ interface PushBatchContext<T extends TypesGeneric$2 = Types$3> extends Context$4<T> {
302
+ ingest?: unknown;
303
+ rule?: Rule<Mapping$1<T>>;
270
304
  }
271
- type InitFn<T extends TypesGeneric$1 = Types$2> = (context: InitContext<T>) => PromiseOrValue<void | false | Config$5<T>>;
272
- type PushFn<T extends TypesGeneric$1 = Types$2> = (event: Event, context: PushContext<T>) => PromiseOrValue<void>;
273
- type PushBatchFn<T extends TypesGeneric$1 = Types$2> = (batch: Batch<Mapping$1<T>>, context: PushBatchContext<T>) => void;
305
+ type InitFn$1<T extends TypesGeneric$2 = Types$3> = (context: Context$4<T>) => PromiseOrValue<void | false | Config$6<T>>;
306
+ type PushFn<T extends TypesGeneric$2 = Types$3> = (event: Event, context: PushContext<T>) => PromiseOrValue<void | unknown>;
307
+ type PushBatchFn<T extends TypesGeneric$2 = Types$3> = (batch: Batch<Mapping$1<T>>, context: PushBatchContext<T>) => void;
274
308
  type PushEvent<Mapping = unknown> = {
275
309
  event: Event;
276
310
  mapping?: Rule<Mapping>;
@@ -289,38 +323,32 @@ interface BatchRegistry<Mapping> {
289
323
  };
290
324
  }
291
325
  type Data$1 = Property | undefined | Array<Property | undefined>;
292
- type Ref = {
293
- id: string;
294
- destination: Instance$2;
295
- };
326
+ interface Ref {
327
+ type: string;
328
+ data?: unknown;
329
+ error?: unknown;
330
+ }
296
331
  type Push$1 = {
297
332
  queue?: Events;
298
333
  error?: unknown;
299
334
  };
300
335
  type DLQ = Array<[Event, unknown]>;
301
- type Result$1 = {
302
- successful: Array<Ref>;
303
- queued: Array<Ref>;
304
- failed: Array<Ref>;
305
- };
306
336
 
307
337
  type destination_Batch<Mapping> = Batch<Mapping>;
308
338
  type destination_BatchRegistry<Mapping> = BatchRegistry<Mapping>;
309
- type destination_Code<T extends TypesGeneric$1 = Types$2> = Code<T>;
339
+ type destination_Code<T extends TypesGeneric$2 = Types$3> = Code<T>;
310
340
  type destination_DLQ = DLQ;
311
341
  type destination_Destinations = Destinations;
312
- type destination_InitContext<T extends TypesGeneric$1 = Types$2> = InitContext<T>;
313
342
  type destination_InitDestinations = InitDestinations;
314
- type destination_InitFn<T extends TypesGeneric$1 = Types$2> = InitFn<T>;
315
- type destination_PushBatchContext<T extends TypesGeneric$1 = Types$2> = PushBatchContext<T>;
316
- type destination_PushBatchFn<T extends TypesGeneric$1 = Types$2> = PushBatchFn<T>;
317
- type destination_PushContext<T extends TypesGeneric$1 = Types$2> = PushContext<T>;
343
+ type destination_PushBatchContext<T extends TypesGeneric$2 = Types$3> = PushBatchContext<T>;
344
+ type destination_PushBatchFn<T extends TypesGeneric$2 = Types$3> = PushBatchFn<T>;
345
+ type destination_PushContext<T extends TypesGeneric$2 = Types$3> = PushContext<T>;
318
346
  type destination_PushEvent<Mapping = unknown> = PushEvent<Mapping>;
319
347
  type destination_PushEvents<Mapping = unknown> = PushEvents<Mapping>;
320
- type destination_PushFn<T extends TypesGeneric$1 = Types$2> = PushFn<T>;
348
+ type destination_PushFn<T extends TypesGeneric$2 = Types$3> = PushFn<T>;
321
349
  type destination_Ref = Ref;
322
350
  declare namespace destination {
323
- export type { BaseEnv$1 as BaseEnv, destination_Batch as Batch, destination_BatchRegistry as BatchRegistry, destination_Code as Code, 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 };
351
+ export type { BaseEnv$2 as BaseEnv, destination_Batch as Batch, destination_BatchRegistry as BatchRegistry, destination_Code as Code, Config$6 as Config, Context$4 as Context, destination_DLQ as DLQ, Data$1 as Data, destination_Destinations as Destinations, Env$2 as Env, Init$2 as Init, destination_InitDestinations as InitDestinations, InitFn$1 as InitFn, InitSettings$2 as InitSettings, Instance$3 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, Settings$2 as Settings, Types$3 as Types, TypesGeneric$2 as TypesGeneric, TypesOf$2 as TypesOf };
324
352
  }
325
353
 
326
354
  interface EventFn<R = Promise<PushResult>> {
@@ -328,14 +356,14 @@ interface EventFn<R = Promise<PushResult>> {
328
356
  (event: string): R;
329
357
  (event: string, data: Properties): R;
330
358
  }
331
- interface Fn$1<R = Promise<PushResult>, Config = unknown> extends EventFn<R>, WalkerCommands<R, Config> {
359
+ interface Fn$2<R = Promise<PushResult>, Config = unknown> extends EventFn<R>, WalkerCommands<R, Config> {
332
360
  }
333
361
  interface WalkerCommands<R = Promise<PushResult>, Config = unknown> {
334
362
  (event: 'walker config', config: Partial<Config>): R;
335
363
  (event: 'walker consent', consent: Consent): R;
336
- <T extends Types$2>(event: 'walker destination', destination: Init$1<T> | Instance$2<T>, config?: Config$5<T>): R;
364
+ <T extends Types$3>(event: 'walker destination', destination: Init$2<T> | Instance$3<T>, config?: Config$6<T>): R;
337
365
  <K extends keyof Functions>(event: 'walker hook', name: K, hookFn: Functions[K]): R;
338
- (event: 'walker on', type: Types$1, rules: SingleOrArray<Options>): R;
366
+ (event: 'walker on', type: Types$2, rules: SingleOrArray<Options>): R;
339
367
  (event: 'walker user', user: User): R;
340
368
  (event: 'walker run', runState: {
341
369
  consent?: Consent;
@@ -346,9 +374,12 @@ interface WalkerCommands<R = Promise<PushResult>, Config = unknown> {
346
374
  }
347
375
  type Event$1<R = Promise<PushResult>> = (partialEvent: DeepPartialEvent) => R;
348
376
  type PushData<Config = unknown> = DeepPartial<Config> | Consent | User | Properties;
349
- interface PushResult extends Result$1 {
350
- event?: Event;
377
+ interface PushResult {
351
378
  ok: boolean;
379
+ event?: Event;
380
+ done?: Record<string, Ref>;
381
+ queued?: Record<string, Ref>;
382
+ failed?: Record<string, Ref>;
352
383
  }
353
384
  type Layer = Array<IArguments | DeepPartialEvent | unknown[]>;
354
385
 
@@ -358,7 +389,7 @@ type elb_PushData<Config = unknown> = PushData<Config>;
358
389
  type elb_PushResult = PushResult;
359
390
  type elb_WalkerCommands<R = Promise<PushResult>, Config = unknown> = WalkerCommands<R, Config>;
360
391
  declare namespace elb {
361
- export type { Event$1 as Event, elb_EventFn as EventFn, Fn$1 as Fn, elb_Layer as Layer, elb_PushData as PushData, elb_PushResult as PushResult, elb_WalkerCommands as WalkerCommands };
392
+ export type { Event$1 as Event, elb_EventFn as EventFn, Fn$2 as Fn, elb_Layer as Layer, elb_PushData as PushData, elb_PushResult as PushResult, elb_WalkerCommands as WalkerCommands };
362
393
  }
363
394
 
364
395
  /**
@@ -489,7 +520,7 @@ interface Setup {
489
520
  * Named flow configurations.
490
521
  * If only one flow exists, it's auto-selected.
491
522
  */
492
- flows: Record<string, Config$4>;
523
+ flows: Record<string, Config$5>;
493
524
  }
494
525
  /**
495
526
  * Single flow configuration.
@@ -501,7 +532,7 @@ interface Setup {
501
532
  *
502
533
  * Variables/definitions cascade: source/destination > config > setup
503
534
  */
504
- interface Config$4 {
535
+ interface Config$5 {
505
536
  /**
506
537
  * Web platform configuration.
507
538
  * Presence indicates web platform (browser-based tracking).
@@ -575,6 +606,34 @@ interface Config$4 {
575
606
  * ```
576
607
  */
577
608
  destinations?: Record<string, DestinationReference>;
609
+ /**
610
+ * Transformer configurations (event transformation).
611
+ *
612
+ * @remarks
613
+ * Transformers transform events in the pipeline:
614
+ * - Pre-collector: Between sources and collector
615
+ * - Post-collector: Between collector and destinations
616
+ *
617
+ * Key = unique transformer identifier (referenced by source.next or destination.before)
618
+ * Value = transformer reference with package and config
619
+ *
620
+ * @example
621
+ * ```json
622
+ * {
623
+ * "transformers": {
624
+ * "enrich": {
625
+ * "package": "@walkeros/transformer-enricher",
626
+ * "config": { "apiUrl": "https://api.example.com" },
627
+ * "next": "validate"
628
+ * },
629
+ * "validate": {
630
+ * "package": "@walkeros/transformer-validator"
631
+ * }
632
+ * }
633
+ * }
634
+ * ```
635
+ */
636
+ transformers?: Record<string, TransformerReference>;
578
637
  /**
579
638
  * Collector configuration (event processing).
580
639
  *
@@ -707,6 +766,77 @@ interface SourceReference {
707
766
  * Overrides flow and setup definitions.
708
767
  */
709
768
  definitions?: Definitions;
769
+ /**
770
+ * First transformer in post-source chain.
771
+ *
772
+ * @remarks
773
+ * Name of the transformer to execute after this source captures an event.
774
+ * If omitted, events route directly to the collector.
775
+ */
776
+ next?: string;
777
+ }
778
+ /**
779
+ * Transformer reference with inline package syntax.
780
+ *
781
+ * @remarks
782
+ * References a transformer package and provides configuration.
783
+ * Transformers transform events in the pipeline between sources and destinations.
784
+ */
785
+ interface TransformerReference {
786
+ /**
787
+ * Package specifier with optional version.
788
+ *
789
+ * @remarks
790
+ * Same format as SourceReference.package
791
+ *
792
+ * @example
793
+ * "package": "@walkeros/transformer-enricher@1.0.0"
794
+ */
795
+ package: string;
796
+ /**
797
+ * Resolved import variable name.
798
+ *
799
+ * @remarks
800
+ * Auto-resolved from packages[package].imports[0] during getFlowConfig().
801
+ * Can also be provided explicitly for advanced use cases.
802
+ */
803
+ code?: string;
804
+ /**
805
+ * Transformer-specific configuration.
806
+ *
807
+ * @remarks
808
+ * Structure depends on the transformer package.
809
+ * Passed to the transformer's initialization function.
810
+ */
811
+ config?: unknown;
812
+ /**
813
+ * Transformer environment configuration.
814
+ *
815
+ * @remarks
816
+ * Environment-specific settings for the transformer.
817
+ * Merged with default transformer environment.
818
+ */
819
+ env?: unknown;
820
+ /**
821
+ * Next transformer in chain.
822
+ *
823
+ * @remarks
824
+ * Name of the next transformer to execute after this one.
825
+ * If omitted:
826
+ * - Pre-collector: routes to collector
827
+ * - Post-collector: routes to destination
828
+ */
829
+ next?: string;
830
+ /**
831
+ * Transformer-level variables (highest priority in cascade).
832
+ * Overrides flow and setup variables.
833
+ */
834
+ variables?: Variables;
835
+ /**
836
+ * Transformer-level definitions (highest priority in cascade).
837
+ * Overrides flow and setup definitions.
838
+ */
839
+ definitions?: Definitions;
710
840
  }
711
841
  /**
712
842
  * Destination reference with inline package syntax.
@@ -785,6 +915,14 @@ interface DestinationReference {
785
915
  * Overrides flow and setup definitions.
786
916
  */
787
917
  definitions?: Definitions;
918
+ /**
919
+ * First transformer in pre-destination chain.
920
+ *
921
+ * @remarks
922
+ * Name of the transformer to execute before sending events to this destination.
923
+ * If omitted, events are sent directly from the collector.
924
+ */
925
+ before?: string;
788
926
  }
789
927
 
790
928
  type flow_Definitions = Definitions;
@@ -794,10 +932,11 @@ type flow_Primitive = Primitive;
794
932
  type flow_Server = Server;
795
933
  type flow_Setup = Setup;
796
934
  type flow_SourceReference = SourceReference;
935
+ type flow_TransformerReference = TransformerReference;
797
936
  type flow_Variables = Variables;
798
937
  type flow_Web = Web;
799
938
  declare namespace flow {
800
- 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 };
939
+ export type { Config$5 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_TransformerReference as TransformerReference, flow_Variables as Variables, flow_Web as Web };
801
940
  }
802
941
 
803
942
  type AnyFunction$1<P extends unknown[] = never[], R = unknown> = (...args: P) => R;
@@ -864,7 +1003,7 @@ type Handler = (level: Level, message: string, context: LogContext, scope: strin
864
1003
  * Logger instance with scoping support
865
1004
  * All logs automatically include trace path from scoping
866
1005
  */
867
- interface Instance$1 {
1006
+ interface Instance$2 {
868
1007
  /**
869
1008
  * Log an error message (always visible unless silenced)
870
1009
  */
@@ -887,12 +1026,12 @@ interface Instance$1 {
887
1026
  * @param name - Scope name (e.g., destination type, destination key)
888
1027
  * @returns A new logger instance with the scope applied
889
1028
  */
890
- scope: (name: string) => Instance$1;
1029
+ scope: (name: string) => Instance$2;
891
1030
  }
892
1031
  /**
893
1032
  * Logger configuration options
894
1033
  */
895
- interface Config$3 {
1034
+ interface Config$4 {
896
1035
  /**
897
1036
  * Minimum log level to display
898
1037
  * @default Level.ERROR
@@ -915,7 +1054,7 @@ interface InternalConfig {
915
1054
  /**
916
1055
  * Logger factory function type
917
1056
  */
918
- type Factory = (config?: Config$3) => Instance$1;
1057
+ type Factory = (config?: Config$4) => Instance$2;
919
1058
 
920
1059
  type logger_DefaultHandler = DefaultHandler;
921
1060
  type logger_ErrorContext = ErrorContext;
@@ -928,14 +1067,14 @@ type logger_LogContext = LogContext;
928
1067
  type logger_LogFn = LogFn;
929
1068
  type logger_ThrowFn = ThrowFn;
930
1069
  declare namespace logger {
931
- 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 };
1070
+ export { type Config$4 as Config, type logger_DefaultHandler as DefaultHandler, type logger_ErrorContext as ErrorContext, type logger_Factory as Factory, type logger_Handler as Handler, type Instance$2 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 };
932
1071
  }
933
1072
 
934
1073
  /**
935
1074
  * Shared mapping configuration interface.
936
1075
  * Used by both Source.Config and Destination.Config.
937
1076
  */
938
- interface Config$2<T = unknown> {
1077
+ interface Config$3<T = unknown> {
939
1078
  consent?: Consent;
940
1079
  data?: Value | Values;
941
1080
  mapping?: Rules<Rule<T>>;
@@ -949,7 +1088,7 @@ interface Rules<T = Rule> {
949
1088
  }
950
1089
  interface Rule<Settings = unknown> {
951
1090
  batch?: number;
952
- batchFn?: (destination: Instance$2, collector: Instance$3) => void;
1091
+ batchFn?: (destination: Instance$3, collector: Instance$4) => void;
953
1092
  batched?: Batch<Settings>;
954
1093
  condition?: Condition;
955
1094
  consent?: Consent;
@@ -970,7 +1109,7 @@ type ValueType = string | ValueConfig;
970
1109
  interface ValueConfig {
971
1110
  condition?: Condition;
972
1111
  consent?: Consent;
973
- fn?: Fn;
1112
+ fn?: Fn$1;
974
1113
  key?: string;
975
1114
  loop?: Loop;
976
1115
  map?: Map;
@@ -978,22 +1117,21 @@ interface ValueConfig {
978
1117
  validate?: Validate;
979
1118
  value?: PropertyType;
980
1119
  }
981
- type Condition = (value: DeepPartialEvent | unknown, mapping?: Value, collector?: Instance$3) => PromiseOrValue<boolean>;
982
- type Fn = (value: DeepPartialEvent | unknown, mapping: Value, options: Options$1) => PromiseOrValue<Property | unknown>;
1120
+ type Condition = (value: DeepPartialEvent | unknown, mapping?: Value, collector?: Instance$4) => PromiseOrValue<boolean>;
1121
+ type Fn$1 = (value: DeepPartialEvent | unknown, mapping: Value, options: Options$1) => PromiseOrValue<Property | unknown>;
983
1122
  type Loop = [Value, Value];
984
1123
  type Map = {
985
1124
  [key: string]: Value;
986
1125
  };
987
1126
  interface Options$1 {
988
1127
  consent?: Consent;
989
- collector?: Instance$3;
1128
+ collector?: Instance$4;
990
1129
  props?: unknown;
991
1130
  }
992
1131
  type Validate = (value?: unknown) => PromiseOrValue<boolean>;
993
1132
 
994
1133
  type mapping_Condition = Condition;
995
1134
  type mapping_Data = Data;
996
- type mapping_Fn = Fn;
997
1135
  type mapping_Loop = Loop;
998
1136
  type mapping_Map = Map;
999
1137
  type mapping_Policy = Policy;
@@ -1006,25 +1144,25 @@ type mapping_ValueConfig = ValueConfig;
1006
1144
  type mapping_ValueType = ValueType;
1007
1145
  type mapping_Values = Values;
1008
1146
  declare namespace mapping {
1009
- export type { mapping_Condition as Condition, Config$2 as Config, mapping_Data as Data, mapping_Fn as Fn, mapping_Loop as Loop, mapping_Map as Map, Options$1 as Options, mapping_Policy as Policy, mapping_Result as Result, mapping_Rule as Rule, mapping_Rules as Rules, mapping_Validate as Validate, mapping_Value as Value, mapping_ValueConfig as ValueConfig, mapping_ValueType as ValueType, mapping_Values as Values };
1147
+ export type { mapping_Condition as Condition, Config$3 as Config, mapping_Data as Data, Fn$1 as Fn, mapping_Loop as Loop, mapping_Map as Map, Options$1 as Options, mapping_Policy as Policy, mapping_Result as Result, mapping_Rule as Rule, mapping_Rules as Rules, mapping_Validate as Validate, mapping_Value as Value, mapping_ValueConfig as ValueConfig, mapping_ValueType as ValueType, mapping_Values as Values };
1010
1148
  }
1011
1149
 
1012
- type Config$1 = {
1150
+ type Config$2 = {
1013
1151
  consent?: Array<ConsentConfig>;
1014
1152
  ready?: Array<ReadyConfig>;
1015
1153
  run?: Array<RunConfig>;
1016
1154
  session?: Array<SessionConfig>;
1017
1155
  };
1018
- type Types$1 = keyof Config$1;
1156
+ type Types$2 = keyof Config$2;
1019
1157
  interface EventContextMap {
1020
1158
  consent: Consent;
1021
1159
  session: SessionData;
1022
1160
  ready: undefined;
1023
1161
  run: undefined;
1024
1162
  }
1025
- type EventContext<T extends Types$1> = EventContextMap[T];
1163
+ type EventContext<T extends Types$2> = EventContextMap[T];
1026
1164
  type AnyEventContext = EventContextMap[keyof EventContextMap];
1027
- interface Context$1 {
1165
+ interface Context$3 {
1028
1166
  consent?: Consent;
1029
1167
  session?: unknown;
1030
1168
  }
@@ -1032,13 +1170,13 @@ type Options = ConsentConfig | ReadyConfig | RunConfig | SessionConfig;
1032
1170
  interface ConsentConfig {
1033
1171
  [key: string]: ConsentFn;
1034
1172
  }
1035
- type ConsentFn = (collector: Instance$3, consent: Consent) => void;
1173
+ type ConsentFn = (collector: Instance$4, consent: Consent) => void;
1036
1174
  type ReadyConfig = ReadyFn;
1037
- type ReadyFn = (collector: Instance$3) => void;
1175
+ type ReadyFn = (collector: Instance$4) => void;
1038
1176
  type RunConfig = RunFn;
1039
- type RunFn = (collector: Instance$3) => void;
1177
+ type RunFn = (collector: Instance$4) => void;
1040
1178
  type SessionConfig = SessionFn;
1041
- type SessionFn = (collector: Instance$3, session?: unknown) => void;
1179
+ type SessionFn = (collector: Instance$4, session?: unknown) => void;
1042
1180
  interface OnConfig {
1043
1181
  consent?: ConsentConfig[];
1044
1182
  ready?: ReadyConfig[];
@@ -1046,16 +1184,16 @@ interface OnConfig {
1046
1184
  session?: SessionConfig[];
1047
1185
  [key: string]: ConsentConfig[] | ReadyConfig[] | RunConfig[] | SessionConfig[] | undefined;
1048
1186
  }
1049
- type OnFn<T extends TypesGeneric$1 = Types$2> = (type: Types$1, context: Context$2<T>) => PromiseOrValue<void>;
1050
- type OnFnRuntime = (type: Types$1, context: Context$2) => PromiseOrValue<void>;
1187
+ type OnFn<T extends TypesGeneric$2 = Types$3> = (type: Types$2, context: Context$4<T>) => PromiseOrValue<void>;
1188
+ type OnFnRuntime = (type: Types$2, context: Context$4) => PromiseOrValue<void>;
1051
1189
 
1052
1190
  type on_AnyEventContext = AnyEventContext;
1053
1191
  type on_ConsentConfig = ConsentConfig;
1054
1192
  type on_ConsentFn = ConsentFn;
1055
- type on_EventContext<T extends Types$1> = EventContext<T>;
1193
+ type on_EventContext<T extends Types$2> = EventContext<T>;
1056
1194
  type on_EventContextMap = EventContextMap;
1057
1195
  type on_OnConfig = OnConfig;
1058
- type on_OnFn<T extends TypesGeneric$1 = Types$2> = OnFn<T>;
1196
+ type on_OnFn<T extends TypesGeneric$2 = Types$3> = OnFn<T>;
1059
1197
  type on_OnFnRuntime = OnFnRuntime;
1060
1198
  type on_Options = Options;
1061
1199
  type on_ReadyConfig = ReadyConfig;
@@ -1065,10 +1203,138 @@ type on_RunFn = RunFn;
1065
1203
  type on_SessionConfig = SessionConfig;
1066
1204
  type on_SessionFn = SessionFn;
1067
1205
  declare namespace on {
1068
- export type { on_AnyEventContext as AnyEventContext, Config$1 as Config, on_ConsentConfig as ConsentConfig, on_ConsentFn as ConsentFn, Context$1 as Context, on_EventContext as EventContext, on_EventContextMap as EventContextMap, on_OnConfig as OnConfig, on_OnFn as OnFn, on_OnFnRuntime as OnFnRuntime, on_Options as Options, on_ReadyConfig as ReadyConfig, on_ReadyFn as ReadyFn, on_RunConfig as RunConfig, on_RunFn as RunFn, on_SessionConfig as SessionConfig, on_SessionFn as SessionFn, Types$1 as Types };
1206
+ export type { on_AnyEventContext as AnyEventContext, Config$2 as Config, on_ConsentConfig as ConsentConfig, on_ConsentFn as ConsentFn, Context$3 as Context, on_EventContext as EventContext, on_EventContextMap as EventContextMap, on_OnConfig as OnConfig, on_OnFn as OnFn, on_OnFnRuntime as OnFnRuntime, on_Options as Options, on_ReadyConfig as ReadyConfig, on_ReadyFn as ReadyFn, on_RunConfig as RunConfig, on_RunFn as RunFn, on_SessionConfig as SessionConfig, on_SessionFn as SessionFn, Types$2 as Types };
1069
1207
  }
1070
1208
 
1071
- interface Context {
1209
+ /**
1210
+ * Base environment interface for walkerOS transformers.
1211
+ *
1212
+ * Minimal like Destination - just an extensible object.
1213
+ * Transformers receive dependencies through context, not env.
1214
+ */
1215
+ interface BaseEnv$1 {
1216
+ [key: string]: unknown;
1217
+ }
1218
+ /**
1219
+ * Type bundle for transformer generics.
1220
+ * Groups Settings, InitSettings, and Env into a single type parameter.
1221
+ * Follows the Source/Destination pattern.
1222
+ *
1223
+ * @template S - Settings configuration type
1224
+ * @template E - Environment type
1225
+ * @template I - InitSettings configuration type (user input)
1226
+ */
1227
+ interface Types$1<S = unknown, E = BaseEnv$1, I = S> {
1228
+ settings: S;
1229
+ initSettings: I;
1230
+ env: E;
1231
+ }
1232
+ /**
1233
+ * Generic constraint for Types - ensures T has required properties for indexed access.
1234
+ */
1235
+ type TypesGeneric$1 = {
1236
+ settings: any;
1237
+ initSettings: any;
1238
+ env: any;
1239
+ };
1240
+ /**
1241
+ * Type extractors for consistent usage with Types bundle.
1242
+ */
1243
+ type Settings$1<T extends TypesGeneric$1 = Types$1> = T['settings'];
1244
+ type InitSettings$1<T extends TypesGeneric$1 = Types$1> = T['initSettings'];
1245
+ type Env$1<T extends TypesGeneric$1 = Types$1> = T['env'];
1246
+ /**
1247
+ * Inference helper: Extract Types from Instance.
1248
+ */
1249
+ type TypesOf$1<I> = I extends Instance$1<infer T> ? T : never;
1250
+ /**
1251
+ * Transformer configuration.
1252
+ */
1253
+ interface Config$1<T extends TypesGeneric$1 = Types$1> {
1254
+ settings?: InitSettings$1<T>;
1255
+ env?: Env$1<T>;
1256
+ id?: string;
1257
+ logger?: Config$4;
1258
+ next?: string;
1259
+ init?: boolean;
1260
+ }
1261
+ /**
1262
+ * Context provided to transformer functions.
1263
+ * Extends base context with transformer-specific properties.
1264
+ */
1265
+ interface Context$2<T extends TypesGeneric$1 = Types$1> extends Base<Config$1<T>, Env$1<T>> {
1266
+ id: string;
1267
+ ingest?: unknown;
1268
+ }
1269
+ /**
1270
+ * The main transformer function.
1271
+ * Uses DeepPartialEvent for consistency across pre/post collector.
1272
+ *
1273
+ * @param event - The event to process
1274
+ * @param context - Transformer context with collector, config, env, logger
1275
+ * @returns event - continue with modified event
1276
+ * @returns void - continue with current event unchanged (passthrough)
1277
+ * @returns false - stop chain, cancel further processing
1278
+ */
1279
+ type Fn<T extends TypesGeneric$1 = Types$1> = (event: DeepPartialEvent, context: Context$2<T>) => PromiseOrValue<DeepPartialEvent | false | void>;
1280
+ /**
1281
+ * Optional initialization function.
1282
+ * Called once before first push.
1283
+ *
1284
+ * @param context - Transformer context
1285
+ * @returns void - initialization successful
1286
+ * @returns false - initialization failed, skip this transformer
1287
+ * @returns Config<T> - return updated config
1288
+ */
1289
+ type InitFn<T extends TypesGeneric$1 = Types$1> = (context: Context$2<T>) => PromiseOrValue<void | false | Config$1<T>>;
1290
+ /**
1291
+ * Transformer instance returned by Init function.
1292
+ */
1293
+ interface Instance$1<T extends TypesGeneric$1 = Types$1> {
1294
+ type: string;
1295
+ config: Config$1<T>;
1296
+ push: Fn<T>;
1297
+ init?: InitFn<T>;
1298
+ destroy?: () => void | Promise<void>;
1299
+ }
1300
+ /**
1301
+ * Transformer initialization function.
1302
+ * Creates a transformer instance from context.
1303
+ */
1304
+ type Init$1<T extends TypesGeneric$1 = Types$1> = (context: Context$2<Types$1<Partial<Settings$1<T>>, Env$1<T>, InitSettings$1<T>>>) => Instance$1<T> | Promise<Instance$1<T>>;
1305
+ /**
1306
+ * Configuration for initializing a transformer.
1307
+ * Used in collector registration.
1308
+ */
1309
+ type InitTransformer<T extends TypesGeneric$1 = Types$1> = {
1310
+ code: Init$1<T>;
1311
+ config?: Partial<Config$1<T>>;
1312
+ env?: Partial<Env$1<T>>;
1313
+ };
1314
+ /**
1315
+ * Transformers configuration for collector.
1316
+ * Maps transformer IDs to their initialization configurations.
1317
+ */
1318
+ interface InitTransformers {
1319
+ [transformerId: string]: InitTransformer<any>;
1320
+ }
1321
+ /**
1322
+ * Active transformer instances registry.
1323
+ */
1324
+ interface Transformers {
1325
+ [transformerId: string]: Instance$1;
1326
+ }
1327
+
1328
+ type transformer_Fn<T extends TypesGeneric$1 = Types$1> = Fn<T>;
1329
+ type transformer_InitFn<T extends TypesGeneric$1 = Types$1> = InitFn<T>;
1330
+ type transformer_InitTransformer<T extends TypesGeneric$1 = Types$1> = InitTransformer<T>;
1331
+ type transformer_InitTransformers = InitTransformers;
1332
+ type transformer_Transformers = Transformers;
1333
+ declare namespace transformer {
1334
+ export type { BaseEnv$1 as BaseEnv, Config$1 as Config, Context$2 as Context, Env$1 as Env, transformer_Fn as Fn, Init$1 as Init, transformer_InitFn as InitFn, InitSettings$1 as InitSettings, transformer_InitTransformer as InitTransformer, transformer_InitTransformers as InitTransformers, Instance$1 as Instance, Settings$1 as Settings, transformer_Transformers as Transformers, Types$1 as Types, TypesGeneric$1 as TypesGeneric, TypesOf$1 as TypesOf };
1335
+ }
1336
+
1337
+ interface Context$1 {
1072
1338
  city?: string;
1073
1339
  country?: string;
1074
1340
  encoding?: string;
@@ -1081,9 +1347,8 @@ interface Context {
1081
1347
  [key: string]: string | undefined;
1082
1348
  }
1083
1349
 
1084
- type request_Context = Context;
1085
1350
  declare namespace request {
1086
- export type { request_Context as Context };
1351
+ export type { Context$1 as Context };
1087
1352
  }
1088
1353
 
1089
1354
  type Contracts = Array<Contract>;
@@ -1125,8 +1390,8 @@ interface BaseEnv {
1125
1390
  push: PushFn$1;
1126
1391
  command: CommandFn;
1127
1392
  sources?: Sources;
1128
- elb: Fn$1;
1129
- logger: Instance$1;
1393
+ elb: Fn$2;
1394
+ logger: Instance$2;
1130
1395
  }
1131
1396
  /**
1132
1397
  * Type bundle for source generics.
@@ -1138,7 +1403,7 @@ interface BaseEnv {
1138
1403
  * @template E - Environment dependencies type
1139
1404
  * @template I - InitSettings configuration type (user input)
1140
1405
  */
1141
- interface Types<S = unknown, M = unknown, P = Fn$1, E = BaseEnv, I = S> {
1406
+ interface Types<S = unknown, M = unknown, P = Fn$2, E = BaseEnv, I = S> {
1142
1407
  settings: S;
1143
1408
  initSettings: I;
1144
1409
  mapping: M;
@@ -1167,13 +1432,26 @@ type Env<T extends TypesGeneric = Types> = T['env'];
1167
1432
  * Inference helper: Extract Types from Instance
1168
1433
  */
1169
1434
  type TypesOf<I> = I extends Instance<infer T> ? T : never;
1170
- interface Config<T extends TypesGeneric = Types> extends Config$2<Mapping<T>> {
1435
+ interface Config<T extends TypesGeneric = Types> extends Config$3<Mapping<T>> {
1171
1436
  settings?: InitSettings<T>;
1172
1437
  env?: Env<T>;
1173
1438
  id?: string;
1174
- logger?: Config$3;
1439
+ logger?: Config$4;
1175
1440
  disabled?: boolean;
1176
1441
  primary?: boolean;
1442
+ /**
1443
+ * Ingest metadata extraction mapping.
1444
+ * Extracts values from raw request objects (Express req, Lambda event, etc.)
1445
+ * using walkerOS mapping syntax. Extracted data flows to transformers/destinations.
1446
+ *
1447
+ * @example
1448
+ * ingest: {
1449
+ * ip: 'req.ip',
1450
+ * ua: 'req.headers.user-agent',
1451
+ * origin: 'req.headers.origin'
1452
+ * }
1453
+ */
1454
+ ingest?: Data;
1177
1455
  }
1178
1456
  type PartialConfig<T extends TypesGeneric = Types> = Config<Types<Partial<Settings<T>> | Settings<T>, Partial<Mapping<T>> | Mapping<T>, Push<T>, Env<T>>>;
1179
1457
  interface Instance<T extends TypesGeneric = Types> {
@@ -1181,14 +1459,30 @@ interface Instance<T extends TypesGeneric = Types> {
1181
1459
  config: Config<T>;
1182
1460
  push: Push<T>;
1183
1461
  destroy?(): void | Promise<void>;
1184
- on?(event: Types$1, context?: unknown): void | Promise<void>;
1462
+ on?(event: Types$2, context?: unknown): void | Promise<void>;
1463
+ }
1464
+ /**
1465
+ * Context provided to source init function.
1466
+ * Extends base context with source-specific properties.
1467
+ */
1468
+ interface Context<T extends TypesGeneric = Types> extends Base<Partial<Config<T>>, Env<T>> {
1469
+ id: string;
1470
+ /**
1471
+ * Sets ingest metadata for the current request.
1472
+ * Extracts values from the raw request using config.ingest mapping.
1473
+ * The extracted data is passed through to transformers and destinations.
1474
+ *
1475
+ * @param value - Raw request object (Express req, Lambda event, etc.)
1476
+ */
1477
+ setIngest: (value: unknown) => Promise<void>;
1185
1478
  }
1186
- type Init<T extends TypesGeneric = Types> = (config: Partial<Config<T>>, env: Env<T>) => Instance<T> | Promise<Instance<T>>;
1479
+ type Init<T extends TypesGeneric = Types> = (context: Context<T>) => Instance<T> | Promise<Instance<T>>;
1187
1480
  type InitSource<T extends TypesGeneric = Types> = {
1188
1481
  code: Init<T>;
1189
1482
  config?: Partial<Config<T>>;
1190
1483
  env?: Partial<Env<T>>;
1191
1484
  primary?: boolean;
1485
+ next?: string;
1192
1486
  };
1193
1487
  /**
1194
1488
  * Sources configuration for collector.
@@ -1200,6 +1494,7 @@ interface InitSources {
1200
1494
 
1201
1495
  type source_BaseEnv = BaseEnv;
1202
1496
  type source_Config<T extends TypesGeneric = Types> = Config<T>;
1497
+ type source_Context<T extends TypesGeneric = Types> = Context<T>;
1203
1498
  type source_Env<T extends TypesGeneric = Types> = Env<T>;
1204
1499
  type source_Init<T extends TypesGeneric = Types> = Init<T>;
1205
1500
  type source_InitSettings<T extends TypesGeneric = Types> = InitSettings<T>;
@@ -1210,15 +1505,15 @@ type source_Mapping<T extends TypesGeneric = Types> = Mapping<T>;
1210
1505
  type source_PartialConfig<T extends TypesGeneric = Types> = PartialConfig<T>;
1211
1506
  type source_Push<T extends TypesGeneric = Types> = Push<T>;
1212
1507
  type source_Settings<T extends TypesGeneric = Types> = Settings<T>;
1213
- type source_Types<S = unknown, M = unknown, P = Fn$1, E = BaseEnv, I = S> = Types<S, M, P, E, I>;
1508
+ type source_Types<S = unknown, M = unknown, P = Fn$2, E = BaseEnv, I = S> = Types<S, M, P, E, I>;
1214
1509
  type source_TypesGeneric = TypesGeneric;
1215
1510
  type source_TypesOf<I> = TypesOf<I>;
1216
1511
  declare namespace source {
1217
- 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 };
1512
+ export type { source_BaseEnv as BaseEnv, source_Config as Config, source_Context as Context, 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 };
1218
1513
  }
1219
1514
 
1220
1515
  type AnyObject<T = unknown> = Record<string, T>;
1221
- type Elb = Fn$1;
1516
+ type Elb = Fn$2;
1222
1517
  type AnyFunction = (...args: unknown[]) => unknown;
1223
1518
  type SingleOrArray<T> = T | Array<T>;
1224
1519
  type Events = Array<Event>;
@@ -1398,7 +1693,7 @@ declare function packageNameToVariable(packageName: string): string;
1398
1693
  * const prodConfig = getFlowConfig(setup, 'production');
1399
1694
  * ```
1400
1695
  */
1401
- declare function getFlowConfig(setup: Setup, flowName?: string): Config$4;
1696
+ declare function getFlowConfig(setup: Setup, flowName?: string): Config$5;
1402
1697
  /**
1403
1698
  * Get platform from config (web or server).
1404
1699
  *
@@ -1414,7 +1709,7 @@ declare function getFlowConfig(setup: Setup, flowName?: string): Config$4;
1414
1709
  * // Returns "web" or "server"
1415
1710
  * ```
1416
1711
  */
1417
- declare function getPlatform(config: Config$4): 'web' | 'server';
1712
+ declare function getPlatform(config: Config$5): 'web' | 'server';
1418
1713
 
1419
1714
  /**
1420
1715
  * @interface Assign
@@ -1510,7 +1805,7 @@ declare function getGrantedConsent(required: Consent | undefined, state?: Consen
1510
1805
  * }));
1511
1806
  * ```
1512
1807
  */
1513
- declare function createDestination<I extends Instance$2>(baseDestination: I, config: Partial<Config$5<TypesOf$1<I>>>): I;
1808
+ declare function createDestination<I extends Instance$3>(baseDestination: I, config: Partial<Config$6<TypesOf$2<I>>>): I;
1514
1809
 
1515
1810
  /**
1516
1811
  * Creates a complete event with default values.
@@ -1672,7 +1967,7 @@ declare function isString(value: unknown): value is string;
1672
1967
  * // TODO: Consider compile-time stripping of debug logs in production builds
1673
1968
  * // e.g., if (__DEV__) { logger.debug(...) }
1674
1969
  */
1675
- declare function createLogger(config?: Config$3): Instance$1;
1970
+ declare function createLogger(config?: Config$4): Instance$2;
1676
1971
 
1677
1972
  /**
1678
1973
  * Gets the mapping for an event.
@@ -1710,7 +2005,7 @@ declare function getMappingValue(value: DeepPartialEvent | unknown | undefined,
1710
2005
  * @param collector - Collector instance for context
1711
2006
  * @returns Object with transformed event, data, mapping rule, and ignore flag
1712
2007
  */
1713
- declare function processEventMapping<T extends DeepPartialEvent | Event>(event: T, config: Config$2, collector: Instance$3): Promise<{
2008
+ declare function processEventMapping<T extends DeepPartialEvent | Event>(event: T, config: Config$3, collector: Instance$4): Promise<{
1714
2009
  event: T;
1715
2010
  data?: Property;
1716
2011
  mapping?: Rule;
@@ -1789,7 +2084,7 @@ declare function traverseEnv<T extends object>(env: T, replacer: (value: unknown
1789
2084
  * Includes all logger methods as jest.fn() plus tracking of scoped loggers
1790
2085
  * Extends Instance to ensure type compatibility
1791
2086
  */
1792
- interface MockLogger extends Instance$1 {
2087
+ interface MockLogger extends Instance$2 {
1793
2088
  error: jest.Mock;
1794
2089
  info: jest.Mock;
1795
2090
  debug: jest.Mock;
@@ -2043,7 +2338,7 @@ declare function wrapCondition(code: string): Condition;
2043
2338
  * const fn = wrapFn('const parts = value.user.email.split("@"); return parts[1].toUpperCase()');
2044
2339
  * ```
2045
2340
  */
2046
- declare function wrapFn(code: string): Fn;
2341
+ declare function wrapFn(code: string): Fn$1;
2047
2342
  /**
2048
2343
  * Wrap inline code string as Validate function.
2049
2344
  *
@@ -2068,4 +2363,4 @@ declare function wrapFn(code: string): Fn;
2068
2363
  */
2069
2364
  declare function wrapValidate(code: string): Validate;
2070
2365
 
2071
- 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, packageNameToVariable, parseUserAgent, processEventMapping, requestToData, requestToParameter, setByPath, throttle, throwError, transformData, traverseEnv, trim, tryCatch, tryCatchAsync, useHooks, validateEvent, validateProperty, wrapCondition, wrapFn, wrapValidate };
2366
+ export { collector as Collector, Const, context as Context, 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, transformer as Transformer, 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, packageNameToVariable, parseUserAgent, processEventMapping, requestToData, requestToParameter, setByPath, throttle, throwError, transformData, traverseEnv, trim, tryCatch, tryCatchAsync, useHooks, validateEvent, validateProperty, wrapCondition, wrapFn, wrapValidate };