@walkeros/web-destination-segment 3.3.0-next-1776098542393
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/LICENSE +21 -0
- package/README.md +372 -0
- package/dist/dev.d.mts +277 -0
- package/dist/dev.d.ts +277 -0
- package/dist/dev.js +1 -0
- package/dist/dev.js.map +1 -0
- package/dist/dev.mjs +1 -0
- package/dist/dev.mjs.map +1 -0
- package/dist/examples/index.d.mts +234 -0
- package/dist/examples/index.d.ts +234 -0
- package/dist/examples/index.js +14564 -0
- package/dist/examples/index.mjs +14542 -0
- package/dist/index.browser.js +9 -0
- package/dist/index.d.mts +141 -0
- package/dist/index.d.ts +141 -0
- package/dist/index.es5.js +9 -0
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -0
- package/dist/index.mjs +1 -0
- package/dist/index.mjs.map +1 -0
- package/dist/walkerOS.json +1284 -0
- package/package.json +78 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 elbWalker GmbH
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,372 @@
|
|
|
1
|
+
<p align="left">
|
|
2
|
+
<a href="https://www.walkeros.io">
|
|
3
|
+
<img alt="walkerOS" title="walkerOS" src="https://www.walkeros.io/img/walkerOS_logo.svg" width="256px"/>
|
|
4
|
+
</a>
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
# Segment CDP Destination for walkerOS
|
|
8
|
+
|
|
9
|
+
[Source Code](https://github.com/elbwalker/walkerOS/tree/main/packages/web/destinations/segment)
|
|
10
|
+
•
|
|
11
|
+
[NPM Package](https://www.npmjs.com/package/@walkeros/web-destination-segment)
|
|
12
|
+
• [Documentation](https://www.walkeros.io/docs/destinations/web/segment)
|
|
13
|
+
|
|
14
|
+
This package forwards walkerOS events to [Segment](https://segment.com/) — the
|
|
15
|
+
customer data platform that routes your event data to 400+ downstream
|
|
16
|
+
destinations. Built on the official
|
|
17
|
+
[`@segment/analytics-next`](https://www.npmjs.com/package/@segment/analytics-next)
|
|
18
|
+
(Analytics.js 2.0) SDK.
|
|
19
|
+
|
|
20
|
+
walkerOS follows a **source → collector → destination** architecture. This
|
|
21
|
+
Segment destination receives processed events from the walkerOS collector and
|
|
22
|
+
forwards them via the full Segment Spec surface: `track`, `identify`, `group`,
|
|
23
|
+
`page`, and `reset`.
|
|
24
|
+
|
|
25
|
+
## Features
|
|
26
|
+
|
|
27
|
+
- **Default event forwarding** — every walkerOS event becomes
|
|
28
|
+
`analytics.track(name, properties)` with no additional config
|
|
29
|
+
- **Custom event properties** — flatten walkerOS sections with
|
|
30
|
+
`settings.include` (`data_*`, `globals_*`, etc.) or produce fully-shaped
|
|
31
|
+
Segment Spec properties via `mapping.data`
|
|
32
|
+
- **Identity** — destination-level or per-event `settings.identify` resolving to
|
|
33
|
+
`{ userId, traits, anonymousId }`, with runtime state diffing so redundant
|
|
34
|
+
`identify()` calls are skipped
|
|
35
|
+
- **Groups** — `settings.group` with Segment-reserved group traits (`name`,
|
|
36
|
+
`industry`, `employees`, `plan`, ...)
|
|
37
|
+
- **Page views** — first-class `analytics.page(category, name, properties)` via
|
|
38
|
+
explicit `mapping.settings.page` configuration
|
|
39
|
+
- **Reset on logout** — `settings.reset: true` calls `analytics.reset()` so the
|
|
40
|
+
current user identity is cleared
|
|
41
|
+
- **Consent context forwarding** — walkerOS consent state is automatically
|
|
42
|
+
stamped as `context.consent.categoryPreferences` on every call, with optional
|
|
43
|
+
`settings.consent` key remapping
|
|
44
|
+
- **Deferred-load consent pattern** — when `config.consent` is declared,
|
|
45
|
+
`AnalyticsBrowser.load()` is held until the first grant
|
|
46
|
+
- **Ecommerce via the Segment Spec** — walkerOS `mapping.name` + `mapping.data`
|
|
47
|
+
produce PascalCase event names (`Order Completed`) with a `products` array, a
|
|
48
|
+
single `track()` call per order (no loop)
|
|
49
|
+
|
|
50
|
+
## Installation
|
|
51
|
+
|
|
52
|
+
```sh
|
|
53
|
+
npm install @walkeros/web-destination-segment
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## Quick Start
|
|
57
|
+
|
|
58
|
+
```typescript
|
|
59
|
+
import { startFlow } from '@walkeros/collector';
|
|
60
|
+
import { destinationSegment } from '@walkeros/web-destination-segment';
|
|
61
|
+
|
|
62
|
+
await startFlow({
|
|
63
|
+
destinations: {
|
|
64
|
+
segment: {
|
|
65
|
+
code: destinationSegment,
|
|
66
|
+
config: {
|
|
67
|
+
settings: {
|
|
68
|
+
apiKey: 'YOUR_SEGMENT_WRITE_KEY',
|
|
69
|
+
},
|
|
70
|
+
},
|
|
71
|
+
},
|
|
72
|
+
},
|
|
73
|
+
});
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## Configuration
|
|
77
|
+
|
|
78
|
+
### Settings (destination-level)
|
|
79
|
+
|
|
80
|
+
The `Settings` type extends Segment's `InitOptions`, so every passthrough option
|
|
81
|
+
(cookie, storage, integrations, plan, retryQueue, ...) works alongside the
|
|
82
|
+
walkerOS-specific fields listed below.
|
|
83
|
+
|
|
84
|
+
| Name | Type | Description | Required |
|
|
85
|
+
| -------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------- | -------- |
|
|
86
|
+
| `apiKey` | `string` | Your Segment source write key — maps to `writeKey` in `AnalyticsBrowser.load()` | Yes |
|
|
87
|
+
| `identify` | `Mapping.Value` | Destination-level identity mapping resolving to `{ userId, traits, anonymousId }` | No |
|
|
88
|
+
| `group` | `Mapping.Value` | Destination-level group mapping resolving to `{ groupId, traits }` | No |
|
|
89
|
+
| `include` | `string[]` | walkerOS event sections to flatten into Segment `properties` (`data`, `globals`, `context`, `user`, `event`, `all`) | No |
|
|
90
|
+
| `consent` | `Record<string, string>` | Mapping from walkerOS consent keys → Segment `categoryPreferences` keys (e.g. `{ marketing: 'Advertising' }`) | No |
|
|
91
|
+
| `initialPageview` | `boolean` | Default `false` — walkerOS sources handle page tracking, so the SDK's auto pageview is disabled | No |
|
|
92
|
+
| `disableClientPersistence` | `boolean` | Disable all cookie / localStorage writes | No |
|
|
93
|
+
| `integrations` | `object` | Enable/disable downstream Segment destinations. Example: `{ All: true, Mixpanel: false }` | No |
|
|
94
|
+
|
|
95
|
+
### Mapping (`rule.settings`)
|
|
96
|
+
|
|
97
|
+
| Name | Type | Description |
|
|
98
|
+
| ---------- | ----------------------- | ----------------------------------------------------------------------------------------------------------- |
|
|
99
|
+
| `identify` | `Mapping.Value` | Per-event identity override; resolves to `{ userId, traits, anonymousId }` |
|
|
100
|
+
| `group` | `Mapping.Value` | Per-event group assignment; resolves to `{ groupId, traits }` |
|
|
101
|
+
| `page` | `Mapping.Value \| true` | Page call config. `true` → empty `analytics.page()`. Object resolves to `{ category?, name?, properties? }` |
|
|
102
|
+
| `reset` | `Mapping.Value \| true` | Logout trigger. Truthy → `analytics.reset()` |
|
|
103
|
+
| `include` | `string[]` | Override destination-level `include` for this rule |
|
|
104
|
+
|
|
105
|
+
Use `mapping.skip: true` to suppress the default `analytics.track()` call when a
|
|
106
|
+
rule runs identity / group / page side effects only.
|
|
107
|
+
|
|
108
|
+
## Event Properties
|
|
109
|
+
|
|
110
|
+
Two ways to shape Segment track properties:
|
|
111
|
+
|
|
112
|
+
```typescript
|
|
113
|
+
// 1. Flatten walkerOS sections via settings.include
|
|
114
|
+
config: {
|
|
115
|
+
settings: {
|
|
116
|
+
apiKey: 'WRITE_KEY',
|
|
117
|
+
include: ['data', 'globals'], // → data_*, globals_* props on every event
|
|
118
|
+
},
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
// 2. Build Segment-Spec-shaped properties via mapping.data
|
|
122
|
+
mapping: {
|
|
123
|
+
order: {
|
|
124
|
+
complete: {
|
|
125
|
+
name: 'Order Completed',
|
|
126
|
+
data: {
|
|
127
|
+
map: {
|
|
128
|
+
order_id: 'data.id',
|
|
129
|
+
currency: { key: 'data.currency', value: 'EUR' },
|
|
130
|
+
shipping: 'data.shipping',
|
|
131
|
+
tax: 'data.taxes',
|
|
132
|
+
total: 'data.total',
|
|
133
|
+
products: {
|
|
134
|
+
loop: [
|
|
135
|
+
'nested',
|
|
136
|
+
{
|
|
137
|
+
condition: (v) => typeof v?.data?.price === 'number',
|
|
138
|
+
map: {
|
|
139
|
+
product_id: 'data.id',
|
|
140
|
+
name: 'data.name',
|
|
141
|
+
price: 'data.price',
|
|
142
|
+
quantity: { key: 'data.quantity', value: 1 },
|
|
143
|
+
currency: { key: 'data.currency', value: 'EUR' },
|
|
144
|
+
},
|
|
145
|
+
},
|
|
146
|
+
],
|
|
147
|
+
},
|
|
148
|
+
},
|
|
149
|
+
},
|
|
150
|
+
},
|
|
151
|
+
},
|
|
152
|
+
}
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
The Segment Ecommerce Spec uses a **single**
|
|
156
|
+
`track('Order Completed', { products: [...] })` call — not a loop of N revenue
|
|
157
|
+
calls. walkerOS `mapping.data` with a nested `loop` over `nested` builds the
|
|
158
|
+
products array inline.
|
|
159
|
+
|
|
160
|
+
## Identity
|
|
161
|
+
|
|
162
|
+
Destination-level identity fires on every push (with state diffing to skip
|
|
163
|
+
redundant calls):
|
|
164
|
+
|
|
165
|
+
```typescript
|
|
166
|
+
config: {
|
|
167
|
+
settings: {
|
|
168
|
+
apiKey: 'WRITE_KEY',
|
|
169
|
+
identify: {
|
|
170
|
+
map: {
|
|
171
|
+
userId: 'user.id',
|
|
172
|
+
traits: {
|
|
173
|
+
map: {
|
|
174
|
+
email: 'user.email',
|
|
175
|
+
name: 'user.name',
|
|
176
|
+
},
|
|
177
|
+
},
|
|
178
|
+
},
|
|
179
|
+
},
|
|
180
|
+
},
|
|
181
|
+
}
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
Per-event identity uses a mapping rule with `skip: true` so only the identity
|
|
185
|
+
side effect runs (not a default `track()`):
|
|
186
|
+
|
|
187
|
+
```typescript
|
|
188
|
+
mapping: {
|
|
189
|
+
user: {
|
|
190
|
+
login: {
|
|
191
|
+
skip: true,
|
|
192
|
+
settings: {
|
|
193
|
+
identify: {
|
|
194
|
+
map: {
|
|
195
|
+
userId: 'data.user_id',
|
|
196
|
+
traits: {
|
|
197
|
+
map: {
|
|
198
|
+
email: 'data.email',
|
|
199
|
+
plan: 'data.plan',
|
|
200
|
+
},
|
|
201
|
+
},
|
|
202
|
+
},
|
|
203
|
+
},
|
|
204
|
+
},
|
|
205
|
+
},
|
|
206
|
+
},
|
|
207
|
+
}
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
### Reserved Traits (Segment Spec)
|
|
211
|
+
|
|
212
|
+
Use these trait names so downstream destinations recognize them: `email`,
|
|
213
|
+
`name`, `firstName`, `lastName`, `phone`, `avatar`, `birthday`, `plan`,
|
|
214
|
+
`company`, `createdAt`, `title`, `username`, `gender`, `age`.
|
|
215
|
+
|
|
216
|
+
## Groups
|
|
217
|
+
|
|
218
|
+
```typescript
|
|
219
|
+
mapping: {
|
|
220
|
+
company: {
|
|
221
|
+
update: {
|
|
222
|
+
skip: true,
|
|
223
|
+
settings: {
|
|
224
|
+
group: {
|
|
225
|
+
map: {
|
|
226
|
+
groupId: 'data.company_id',
|
|
227
|
+
traits: {
|
|
228
|
+
map: {
|
|
229
|
+
name: 'data.company_name',
|
|
230
|
+
industry: 'data.industry',
|
|
231
|
+
employees: 'data.employees',
|
|
232
|
+
plan: 'data.plan',
|
|
233
|
+
},
|
|
234
|
+
},
|
|
235
|
+
},
|
|
236
|
+
},
|
|
237
|
+
},
|
|
238
|
+
},
|
|
239
|
+
},
|
|
240
|
+
}
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
Reserved Segment group traits: `name`, `industry`, `employees`, `plan`,
|
|
244
|
+
`createdAt`, `description`, `email`, `website`.
|
|
245
|
+
|
|
246
|
+
## Page Views
|
|
247
|
+
|
|
248
|
+
Segment's `page()` is first-class — walkerOS `page view` events should map to
|
|
249
|
+
`analytics.page()`, not `analytics.track('page view')`. Configure explicitly via
|
|
250
|
+
`mapping.settings.page`:
|
|
251
|
+
|
|
252
|
+
```typescript
|
|
253
|
+
mapping: {
|
|
254
|
+
page: {
|
|
255
|
+
view: {
|
|
256
|
+
skip: true,
|
|
257
|
+
settings: {
|
|
258
|
+
page: {
|
|
259
|
+
map: {
|
|
260
|
+
category: 'data.category',
|
|
261
|
+
name: 'data.title',
|
|
262
|
+
properties: {
|
|
263
|
+
map: {
|
|
264
|
+
section: 'data.section',
|
|
265
|
+
},
|
|
266
|
+
},
|
|
267
|
+
},
|
|
268
|
+
},
|
|
269
|
+
},
|
|
270
|
+
},
|
|
271
|
+
},
|
|
272
|
+
}
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
Or the minimal form (`true`) that fires an empty `analytics.page()` and relies
|
|
276
|
+
on the SDK's automatic url/path/referrer/title collection:
|
|
277
|
+
|
|
278
|
+
```typescript
|
|
279
|
+
mapping: {
|
|
280
|
+
page: {
|
|
281
|
+
view: {
|
|
282
|
+
skip: true,
|
|
283
|
+
settings: {
|
|
284
|
+
page: true,
|
|
285
|
+
},
|
|
286
|
+
},
|
|
287
|
+
},
|
|
288
|
+
}
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
## Consent
|
|
292
|
+
|
|
293
|
+
The destination supports two complementary consent mechanisms:
|
|
294
|
+
|
|
295
|
+
**Automatic context forwarding.** When `settings.consent` is configured, the
|
|
296
|
+
destination stamps every `track`, `identify`, `group`, and `page` call with
|
|
297
|
+
`context.consent.categoryPreferences`:
|
|
298
|
+
|
|
299
|
+
```typescript
|
|
300
|
+
config: {
|
|
301
|
+
settings: {
|
|
302
|
+
apiKey: 'WRITE_KEY',
|
|
303
|
+
consent: {
|
|
304
|
+
analytics: 'Analytics',
|
|
305
|
+
marketing: 'Advertising',
|
|
306
|
+
},
|
|
307
|
+
},
|
|
308
|
+
}
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
When the walker emits an event with
|
|
312
|
+
`consent: { analytics: true, marketing: true }`, the destination calls
|
|
313
|
+
`analytics.track(name, props, { context: { consent: { categoryPreferences: { Analytics: true, Advertising: true } } } })`.
|
|
314
|
+
|
|
315
|
+
**Deferred-load consent pattern.** When `config.consent` is declared,
|
|
316
|
+
`AnalyticsBrowser.load()` is held until the first `walker consent` command that
|
|
317
|
+
grants all required keys. Once granted, the SDK loads and all queued events
|
|
318
|
+
flush:
|
|
319
|
+
|
|
320
|
+
```typescript
|
|
321
|
+
destinations: {
|
|
322
|
+
segment: {
|
|
323
|
+
code: destinationSegment,
|
|
324
|
+
config: {
|
|
325
|
+
consent: { analytics: true },
|
|
326
|
+
settings: { apiKey: 'WRITE_KEY' },
|
|
327
|
+
},
|
|
328
|
+
},
|
|
329
|
+
}
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
This is the primary consent mechanism for Segment, since Segment's SDK has no
|
|
333
|
+
`optOut()` method — the only way to enforce consent is to avoid loading the SDK
|
|
334
|
+
in the first place.
|
|
335
|
+
|
|
336
|
+
## Reset (Logout)
|
|
337
|
+
|
|
338
|
+
```typescript
|
|
339
|
+
mapping: {
|
|
340
|
+
user: {
|
|
341
|
+
logout: {
|
|
342
|
+
skip: true,
|
|
343
|
+
settings: {
|
|
344
|
+
reset: true,
|
|
345
|
+
},
|
|
346
|
+
},
|
|
347
|
+
},
|
|
348
|
+
}
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
`analytics.reset()` clears the stored `userId`, `anonymousId`, and traits, then
|
|
352
|
+
generates a fresh anonymous ID.
|
|
353
|
+
|
|
354
|
+
## Scope Notes
|
|
355
|
+
|
|
356
|
+
- **`alias()` and `screen()`** are intentionally deferred. `alias()` is a legacy
|
|
357
|
+
identity-linking method (most identity resolution happens server-side in
|
|
358
|
+
Segment Profiles); `screen()` is mobile-only.
|
|
359
|
+
- **Plugins, source middleware, and destination middleware** cannot be
|
|
360
|
+
serialized in JSON flow configs. Register them programmatically on the
|
|
361
|
+
returned `AnalyticsBrowser` instance if needed.
|
|
362
|
+
|
|
363
|
+
## Contribute
|
|
364
|
+
|
|
365
|
+
Feel free to contribute by submitting an
|
|
366
|
+
[issue](https://github.com/elbwalker/walkerOS/issues), starting a
|
|
367
|
+
[discussion](https://github.com/elbwalker/walkerOS/discussions), or getting in
|
|
368
|
+
[contact](https://calendly.com/elb-alexander/30min).
|
|
369
|
+
|
|
370
|
+
## License
|
|
371
|
+
|
|
372
|
+
This project is licensed under the MIT License.
|
package/dist/dev.d.mts
ADDED
|
@@ -0,0 +1,277 @@
|
|
|
1
|
+
import * as _walkeros_core_dev from '@walkeros/core/dev';
|
|
2
|
+
import { z } from '@walkeros/core/dev';
|
|
3
|
+
import { Mapping as Mapping$1, Flow } from '@walkeros/core';
|
|
4
|
+
import { DestinationWeb } from '@walkeros/web-core';
|
|
5
|
+
import { AnalyticsBrowserSettings, InitOptions } from '@segment/analytics-next';
|
|
6
|
+
|
|
7
|
+
declare const SettingsSchema: z.ZodObject<{
|
|
8
|
+
apiKey: z.ZodString;
|
|
9
|
+
cdnURL: z.ZodOptional<z.ZodString>;
|
|
10
|
+
initialPageview: z.ZodOptional<z.ZodBoolean>;
|
|
11
|
+
disableClientPersistence: z.ZodOptional<z.ZodBoolean>;
|
|
12
|
+
disableAutoISOConversion: z.ZodOptional<z.ZodBoolean>;
|
|
13
|
+
retryQueue: z.ZodOptional<z.ZodBoolean>;
|
|
14
|
+
obfuscate: z.ZodOptional<z.ZodBoolean>;
|
|
15
|
+
integrations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
|
|
16
|
+
identify: z.ZodOptional<z.ZodUnknown>;
|
|
17
|
+
group: z.ZodOptional<z.ZodUnknown>;
|
|
18
|
+
consent: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
|
|
19
|
+
}, z.core.$strip>;
|
|
20
|
+
type Settings$1 = z.infer<typeof SettingsSchema>;
|
|
21
|
+
|
|
22
|
+
declare const MappingSchema: z.ZodObject<{
|
|
23
|
+
identify: z.ZodOptional<z.ZodUnknown>;
|
|
24
|
+
group: z.ZodOptional<z.ZodUnknown>;
|
|
25
|
+
page: z.ZodOptional<z.ZodUnknown>;
|
|
26
|
+
reset: z.ZodOptional<z.ZodUnknown>;
|
|
27
|
+
}, z.core.$strip>;
|
|
28
|
+
type Mapping = z.infer<typeof MappingSchema>;
|
|
29
|
+
|
|
30
|
+
declare const settings: _walkeros_core_dev.JSONSchema;
|
|
31
|
+
declare const mapping: _walkeros_core_dev.JSONSchema;
|
|
32
|
+
|
|
33
|
+
type index$1_Mapping = Mapping;
|
|
34
|
+
declare const index$1_MappingSchema: typeof MappingSchema;
|
|
35
|
+
declare const index$1_SettingsSchema: typeof SettingsSchema;
|
|
36
|
+
declare const index$1_mapping: typeof mapping;
|
|
37
|
+
declare const index$1_settings: typeof settings;
|
|
38
|
+
declare namespace index$1 {
|
|
39
|
+
export { type index$1_Mapping as Mapping, index$1_MappingSchema as MappingSchema, type Settings$1 as Settings, index$1_SettingsSchema as SettingsSchema, index$1_mapping as mapping, index$1_settings as settings };
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* Destination-level settings.
|
|
44
|
+
*
|
|
45
|
+
* Extends Segment's `InitOptions` (minus the `group` key which clashes with
|
|
46
|
+
* walkerOS's own `group` mapping) so every passthrough option (cookie,
|
|
47
|
+
* storage, integrations, plan, etc.) keeps IntelliSense intact. walkerOS
|
|
48
|
+
* adds:
|
|
49
|
+
* - `apiKey` (required) — maps to `writeKey` in `AnalyticsBrowser.load()`
|
|
50
|
+
* - `identify` — destination-level identity mapping (Segment `identify()`)
|
|
51
|
+
* - `group` — destination-level group mapping (Segment `group()`)
|
|
52
|
+
* - `include` — event sections flattened into track `properties`
|
|
53
|
+
* - `consent` — walkerOS consent key → Segment category name mapping
|
|
54
|
+
* - `_state` — runtime state (not user-facing, mutated by init/push)
|
|
55
|
+
*/
|
|
56
|
+
interface Settings extends Omit<InitOptions, 'group'> {
|
|
57
|
+
/** Segment write key. Maps to `writeKey` in the load() settings arg. */
|
|
58
|
+
apiKey: string;
|
|
59
|
+
/** walkerOS mapping value resolving to an identity object (userId, traits, anonymousId). */
|
|
60
|
+
identify?: Mapping$1.Value;
|
|
61
|
+
/** walkerOS mapping value resolving to a group object (groupId, traits). */
|
|
62
|
+
group?: Mapping$1.Value;
|
|
63
|
+
/**
|
|
64
|
+
* Mapping from walkerOS consent keys → Segment `categoryPreferences` keys.
|
|
65
|
+
* Example: { marketing: "Advertising", analytics: "Analytics" }
|
|
66
|
+
* If omitted, walkerOS keys are forwarded 1:1.
|
|
67
|
+
*/
|
|
68
|
+
consent?: Record<string, string>;
|
|
69
|
+
/** Runtime state — populated by init() and mutated by push(). Not user-facing. */
|
|
70
|
+
_state?: RuntimeState;
|
|
71
|
+
}
|
|
72
|
+
interface RuntimeState {
|
|
73
|
+
/** Last-set identity values, used to skip redundant identify() calls. */
|
|
74
|
+
lastIdentity?: {
|
|
75
|
+
userId?: string;
|
|
76
|
+
anonymousId?: string;
|
|
77
|
+
traitsHash?: string;
|
|
78
|
+
};
|
|
79
|
+
/** Last-set group assignment, used to skip redundant group() calls. */
|
|
80
|
+
lastGroup?: {
|
|
81
|
+
groupId?: string;
|
|
82
|
+
traitsHash?: string;
|
|
83
|
+
};
|
|
84
|
+
/** Holds the AnalyticsBrowser instance created in init(). */
|
|
85
|
+
analytics?: SegmentAnalytics;
|
|
86
|
+
/** True once load() has been called (may be deferred pending consent). */
|
|
87
|
+
loaded?: boolean;
|
|
88
|
+
}
|
|
89
|
+
/**
|
|
90
|
+
* Segment SDK surface — the subset of @segment/analytics-next the
|
|
91
|
+
* destination actually uses. Mirrors the AnalyticsBrowser instance shape
|
|
92
|
+
* so tests can mock each method individually via env.analytics.
|
|
93
|
+
*/
|
|
94
|
+
interface SegmentAnalytics {
|
|
95
|
+
track: (event: string, properties?: Record<string, unknown>, options?: SegmentEventOptions) => Promise<unknown> | void;
|
|
96
|
+
identify: (userId?: string | Record<string, unknown>, traits?: Record<string, unknown>, options?: SegmentEventOptions) => Promise<unknown> | void;
|
|
97
|
+
group: (groupId: string, traits?: Record<string, unknown>, options?: SegmentEventOptions) => Promise<unknown> | void;
|
|
98
|
+
page: (category?: string | null, name?: string | null, properties?: Record<string, unknown>, options?: SegmentEventOptions) => Promise<unknown> | void;
|
|
99
|
+
alias: (to: string, from?: string, options?: SegmentEventOptions) => Promise<unknown> | void;
|
|
100
|
+
reset: () => Promise<unknown> | void;
|
|
101
|
+
setAnonymousId: (id: string) => Promise<unknown> | void;
|
|
102
|
+
}
|
|
103
|
+
/**
|
|
104
|
+
* Segment event options — the fourth argument to track/identify/group/page
|
|
105
|
+
* that carries context and integration overrides. The destination uses
|
|
106
|
+
* this to stamp consent context on every event.
|
|
107
|
+
*/
|
|
108
|
+
interface SegmentEventOptions {
|
|
109
|
+
context?: {
|
|
110
|
+
consent?: {
|
|
111
|
+
categoryPreferences?: Record<string, boolean>;
|
|
112
|
+
};
|
|
113
|
+
[key: string]: unknown;
|
|
114
|
+
};
|
|
115
|
+
integrations?: Record<string, boolean | Record<string, unknown>>;
|
|
116
|
+
}
|
|
117
|
+
/**
|
|
118
|
+
* The module namespace used for `env?.analytics ?? realSegment`.
|
|
119
|
+
* AnalyticsBrowser is the class; tests mock with a factory that returns
|
|
120
|
+
* an object matching SegmentAnalytics.
|
|
121
|
+
*
|
|
122
|
+
* Task 1 verified: `AnalyticsBrowser.load(settings, options)` returns an
|
|
123
|
+
* `AnalyticsBrowser` instance **synchronously**. The instance buffers
|
|
124
|
+
* method calls until the internal load promise resolves.
|
|
125
|
+
*/
|
|
126
|
+
interface SegmentSDK {
|
|
127
|
+
load: (settings: AnalyticsBrowserSettings, options?: InitOptions) => SegmentAnalytics;
|
|
128
|
+
}
|
|
129
|
+
/**
|
|
130
|
+
* Env — optional SDK override. Production leaves this undefined and the
|
|
131
|
+
* destination falls back to the real @segment/analytics-next module.
|
|
132
|
+
* Tests provide a mock via env.analytics = { ... }.
|
|
133
|
+
*/
|
|
134
|
+
interface Env extends DestinationWeb.Env {
|
|
135
|
+
analytics?: SegmentSDK;
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
declare const init: Env | undefined;
|
|
139
|
+
declare const push: Env;
|
|
140
|
+
/** Simulation tracking paths for CLI --simulate. */
|
|
141
|
+
declare const simulation: string[];
|
|
142
|
+
|
|
143
|
+
declare const env_init: typeof init;
|
|
144
|
+
declare const env_push: typeof push;
|
|
145
|
+
declare const env_simulation: typeof simulation;
|
|
146
|
+
declare namespace env {
|
|
147
|
+
export { env_init as init, env_push as push, env_simulation as simulation };
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
/**
|
|
151
|
+
* Examples may optionally carry destination-level settings.
|
|
152
|
+
* The test runner merges this on top of a base { apiKey: 'test-project' }.
|
|
153
|
+
*/
|
|
154
|
+
type SegmentStepExample = Flow.StepExample & {
|
|
155
|
+
settings?: Partial<Settings>;
|
|
156
|
+
configInclude?: string[];
|
|
157
|
+
};
|
|
158
|
+
/**
|
|
159
|
+
* Default event forwarding — every walkerOS event becomes
|
|
160
|
+
* analytics.track(event.name, properties). With no mapping and no
|
|
161
|
+
* destination-level include, properties is `{}`.
|
|
162
|
+
*/
|
|
163
|
+
declare const defaultEventForwarding: SegmentStepExample;
|
|
164
|
+
/**
|
|
165
|
+
* Wildcard ignore — walkerOS's standard way to drop events. The rule
|
|
166
|
+
* matches but does nothing. The destination fires zero SDK calls.
|
|
167
|
+
*/
|
|
168
|
+
declare const wildcardIgnored: SegmentStepExample;
|
|
169
|
+
/**
|
|
170
|
+
* Destination-level settings.include flattens the walkerOS `data` section
|
|
171
|
+
* into prefixed properties on every push.
|
|
172
|
+
*/
|
|
173
|
+
declare const destinationLevelInclude: SegmentStepExample;
|
|
174
|
+
/**
|
|
175
|
+
* Per-rule settings.include REPLACES destination-level include for the
|
|
176
|
+
* matched rule. Here destination-level sends `data`, but the rule
|
|
177
|
+
* overrides it with `globals` only.
|
|
178
|
+
*/
|
|
179
|
+
declare const ruleIncludeReplaces: SegmentStepExample;
|
|
180
|
+
/**
|
|
181
|
+
* Destination-level settings.identify fires on the first push. The
|
|
182
|
+
* destination resolves the mapping, calls analytics.identify(userId),
|
|
183
|
+
* and records the value in runtime state. Subsequent pushes with the
|
|
184
|
+
* same userId do NOT re-fire identify().
|
|
185
|
+
*/
|
|
186
|
+
declare const destinationLevelIdentify: SegmentStepExample;
|
|
187
|
+
/**
|
|
188
|
+
* Per-event identify with traits — the canonical "user login" pattern.
|
|
189
|
+
* skip: true suppresses the default analytics.track() call because we're
|
|
190
|
+
* running identity side effects only. Matches Segment Spec reserved traits
|
|
191
|
+
* (email, name, plan, company) so downstream destinations recognize them.
|
|
192
|
+
*/
|
|
193
|
+
declare const userLoginIdentify: SegmentStepExample;
|
|
194
|
+
/**
|
|
195
|
+
* Profile update — omit userId. Segment's SDK uses the currently stored
|
|
196
|
+
* userId and merges the traits into the existing trait set.
|
|
197
|
+
*/
|
|
198
|
+
declare const profileUpdateTraitsOnly: SegmentStepExample;
|
|
199
|
+
/**
|
|
200
|
+
* User logout — reset: true fires analytics.reset(), which clears userId,
|
|
201
|
+
* anonymousId, traits, and generates a new anonymous ID.
|
|
202
|
+
* skip: true because we're only running the reset side effect.
|
|
203
|
+
*/
|
|
204
|
+
declare const userLogoutReset: SegmentStepExample;
|
|
205
|
+
/**
|
|
206
|
+
* Per-event group assignment — company update event attaches the user
|
|
207
|
+
* to a company and sets the company's traits in one call.
|
|
208
|
+
*/
|
|
209
|
+
declare const companyUpdateGroup: SegmentStepExample;
|
|
210
|
+
/**
|
|
211
|
+
* Explicit page() call — the canonical Segment pattern for page views.
|
|
212
|
+
* skip: true suppresses the default track() call; settings.page fires
|
|
213
|
+
* analytics.page(category, name, properties) instead.
|
|
214
|
+
*/
|
|
215
|
+
declare const pageViewAsPage: SegmentStepExample;
|
|
216
|
+
/**
|
|
217
|
+
* Minimal page() call — settings.page: true produces an empty
|
|
218
|
+
* analytics.page() relying entirely on SDK auto-collection.
|
|
219
|
+
*/
|
|
220
|
+
declare const pageViewMinimal: SegmentStepExample;
|
|
221
|
+
/**
|
|
222
|
+
* Segment ecommerce spec — Order Completed event. One track() call with
|
|
223
|
+
* a products array. Uses mapping.name to produce the Segment Spec name
|
|
224
|
+
* and mapping.data to build the properties object including the nested
|
|
225
|
+
* products loop. The loop filters via condition to products with prices.
|
|
226
|
+
*/
|
|
227
|
+
declare const orderCompletedEcommerce: SegmentStepExample;
|
|
228
|
+
/**
|
|
229
|
+
* Consent context forwarding — when the event has consent state,
|
|
230
|
+
* the destination automatically stamps every track/identify/group/page
|
|
231
|
+
* call with context.consent.categoryPreferences. settings.consent
|
|
232
|
+
* remaps walkerOS keys to Segment category names.
|
|
233
|
+
*/
|
|
234
|
+
declare const consentContextForwarded: SegmentStepExample;
|
|
235
|
+
/**
|
|
236
|
+
* Consent granted → deferred load fires for the first time. The
|
|
237
|
+
* destination was initialized with consent requirement; on the walker
|
|
238
|
+
* consent command it calls analytics.load(writeKey, initOptions).
|
|
239
|
+
*
|
|
240
|
+
* Uses the canonical StepExample.command='consent' pattern. The full
|
|
241
|
+
* call shape includes both the settings arg and the initOptions arg.
|
|
242
|
+
*/
|
|
243
|
+
declare const consentGrantDeferredLoad: SegmentStepExample;
|
|
244
|
+
/**
|
|
245
|
+
* Consent revoked → no SDK call. The walkerOS consent gate handles
|
|
246
|
+
* blocking subsequent events. The destination's on('consent') handler
|
|
247
|
+
* is a no-op on revocation (Segment has no opt-out method).
|
|
248
|
+
*/
|
|
249
|
+
declare const consentRevokeNoOp: SegmentStepExample;
|
|
250
|
+
|
|
251
|
+
type step_SegmentStepExample = SegmentStepExample;
|
|
252
|
+
declare const step_companyUpdateGroup: typeof companyUpdateGroup;
|
|
253
|
+
declare const step_consentContextForwarded: typeof consentContextForwarded;
|
|
254
|
+
declare const step_consentGrantDeferredLoad: typeof consentGrantDeferredLoad;
|
|
255
|
+
declare const step_consentRevokeNoOp: typeof consentRevokeNoOp;
|
|
256
|
+
declare const step_defaultEventForwarding: typeof defaultEventForwarding;
|
|
257
|
+
declare const step_destinationLevelIdentify: typeof destinationLevelIdentify;
|
|
258
|
+
declare const step_destinationLevelInclude: typeof destinationLevelInclude;
|
|
259
|
+
declare const step_orderCompletedEcommerce: typeof orderCompletedEcommerce;
|
|
260
|
+
declare const step_pageViewAsPage: typeof pageViewAsPage;
|
|
261
|
+
declare const step_pageViewMinimal: typeof pageViewMinimal;
|
|
262
|
+
declare const step_profileUpdateTraitsOnly: typeof profileUpdateTraitsOnly;
|
|
263
|
+
declare const step_ruleIncludeReplaces: typeof ruleIncludeReplaces;
|
|
264
|
+
declare const step_userLoginIdentify: typeof userLoginIdentify;
|
|
265
|
+
declare const step_userLogoutReset: typeof userLogoutReset;
|
|
266
|
+
declare const step_wildcardIgnored: typeof wildcardIgnored;
|
|
267
|
+
declare namespace step {
|
|
268
|
+
export { type step_SegmentStepExample as SegmentStepExample, step_companyUpdateGroup as companyUpdateGroup, step_consentContextForwarded as consentContextForwarded, step_consentGrantDeferredLoad as consentGrantDeferredLoad, step_consentRevokeNoOp as consentRevokeNoOp, step_defaultEventForwarding as defaultEventForwarding, step_destinationLevelIdentify as destinationLevelIdentify, step_destinationLevelInclude as destinationLevelInclude, step_orderCompletedEcommerce as orderCompletedEcommerce, step_pageViewAsPage as pageViewAsPage, step_pageViewMinimal as pageViewMinimal, step_profileUpdateTraitsOnly as profileUpdateTraitsOnly, step_ruleIncludeReplaces as ruleIncludeReplaces, step_userLoginIdentify as userLoginIdentify, step_userLogoutReset as userLogoutReset, step_wildcardIgnored as wildcardIgnored };
|
|
269
|
+
}
|
|
270
|
+
|
|
271
|
+
declare const index_env: typeof env;
|
|
272
|
+
declare const index_step: typeof step;
|
|
273
|
+
declare namespace index {
|
|
274
|
+
export { index_env as env, index_step as step };
|
|
275
|
+
}
|
|
276
|
+
|
|
277
|
+
export { index as examples, index$1 as schemas };
|