@walkeros/web-destination-clarity 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 +148 -0
- package/dist/dev.d.mts +206 -0
- package/dist/dev.d.ts +206 -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 +169 -0
- package/dist/examples/index.d.ts +169 -0
- package/dist/examples/index.js +14408 -0
- package/dist/examples/index.mjs +14386 -0
- package/dist/index.browser.js +1 -0
- package/dist/index.d.mts +81 -0
- package/dist/index.d.ts +81 -0
- package/dist/index.es5.js +1 -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 +1075 -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,148 @@
|
|
|
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
|
+
# Microsoft Clarity Destination for walkerOS
|
|
8
|
+
|
|
9
|
+
[Source Code](https://github.com/elbwalker/walkerOS/tree/main/packages/web/destinations/clarity)
|
|
10
|
+
•
|
|
11
|
+
[NPM Package](https://www.npmjs.com/package/@walkeros/web-destination-clarity)
|
|
12
|
+
• [Documentation](https://www.walkeros.io/docs/destinations/web/clarity)
|
|
13
|
+
|
|
14
|
+
This package forwards walkerOS events to
|
|
15
|
+
[Microsoft Clarity](https://clarity.microsoft.com/) — session replays, heatmaps,
|
|
16
|
+
and behavioural insights for web products. Built on the official
|
|
17
|
+
[`@microsoft/clarity`](https://www.npmjs.com/package/@microsoft/clarity) SDK.
|
|
18
|
+
|
|
19
|
+
walkerOS follows a **source → collector → destination** architecture. This
|
|
20
|
+
Clarity destination receives processed events from the walkerOS collector and
|
|
21
|
+
forwards them as Clarity events, tags, identities, and consent updates.
|
|
22
|
+
|
|
23
|
+
## Features
|
|
24
|
+
|
|
25
|
+
- **Default event forwarding** — every walkerOS event becomes
|
|
26
|
+
`Clarity.event(name)` with no additional config
|
|
27
|
+
- **Custom tags** — flatten walkerOS event sections (`settings.include`) or
|
|
28
|
+
define explicit tag maps (`mapping.settings.set`)
|
|
29
|
+
- **Identity** — resolve mapping values into positional arguments for
|
|
30
|
+
`Clarity.identify(...)`
|
|
31
|
+
- **Session priority** — flag important sessions via `Clarity.upgrade(reason)`
|
|
32
|
+
so Clarity retains them beyond sampling
|
|
33
|
+
- **Consent translation** — explicit `settings.consent` table translates
|
|
34
|
+
walkerOS consent keys to Clarity's `ConsentV2` categories
|
|
35
|
+
|
|
36
|
+
## Installation
|
|
37
|
+
|
|
38
|
+
```sh
|
|
39
|
+
npm install @walkeros/web-destination-clarity
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Quick Start
|
|
43
|
+
|
|
44
|
+
```typescript
|
|
45
|
+
import { startFlow } from '@walkeros/collector';
|
|
46
|
+
import { destinationClarity } from '@walkeros/web-destination-clarity';
|
|
47
|
+
|
|
48
|
+
await startFlow({
|
|
49
|
+
destinations: {
|
|
50
|
+
clarity: {
|
|
51
|
+
code: destinationClarity,
|
|
52
|
+
config: {
|
|
53
|
+
settings: {
|
|
54
|
+
apiKey: '3t0wlogvdz', // your Clarity project ID
|
|
55
|
+
consent: {
|
|
56
|
+
analytics: 'analytics_Storage',
|
|
57
|
+
marketing: 'ad_Storage',
|
|
58
|
+
},
|
|
59
|
+
},
|
|
60
|
+
},
|
|
61
|
+
},
|
|
62
|
+
},
|
|
63
|
+
});
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## Configuration
|
|
67
|
+
|
|
68
|
+
### Settings (destination-level)
|
|
69
|
+
|
|
70
|
+
| Name | Type | Description | Required |
|
|
71
|
+
| ---------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------- | -------- |
|
|
72
|
+
| `apiKey` | `string` | Microsoft Clarity project ID (from Clarity → Settings → Setup) | Yes |
|
|
73
|
+
| `consent` | `Record<string, 'analytics_Storage' \| 'ad_Storage'>` | Translation table from walkerOS consent keys to Clarity `ConsentV2` categories | No |
|
|
74
|
+
| `include` | `string[]` | walkerOS event sections to flatten into Clarity tags (`data`, `globals`, `context`, `user`, …) | No |
|
|
75
|
+
| `identify` | `Mapping.Value` | Destination-level identity mapping; resolves to positional args for `Clarity.identify(...)` | No |
|
|
76
|
+
|
|
77
|
+
### Mapping (`rule.settings`)
|
|
78
|
+
|
|
79
|
+
| Name | Type | Description |
|
|
80
|
+
| ---------- | --------------- | ------------------------------------------------------------------------------------------------------- |
|
|
81
|
+
| `identify` | `Mapping.Value` | Per-event identity override; resolves to `{ customId, customSessionId?, customPageId?, friendlyName? }` |
|
|
82
|
+
| `include` | `string[]` | Override destination-level `include` for this rule |
|
|
83
|
+
| `set` | `Mapping.Value` | Explicit custom tag map; resolved object keys become `Clarity.setTag(key, value)` calls |
|
|
84
|
+
| `upgrade` | `Mapping.Value` | Session priority reason; resolves to a string → `Clarity.upgrade(reason)` |
|
|
85
|
+
|
|
86
|
+
## Custom Tags
|
|
87
|
+
|
|
88
|
+
Two ways to attach custom tags to a Clarity session:
|
|
89
|
+
|
|
90
|
+
```typescript
|
|
91
|
+
// 1. Flatten walkerOS sections with settings.include
|
|
92
|
+
config: {
|
|
93
|
+
settings: {
|
|
94
|
+
apiKey: '3t0wlogvdz',
|
|
95
|
+
include: ['data', 'user'], // → data_*, user_* tags on every event
|
|
96
|
+
},
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
// 2. Explicit per-event tags via mapping.settings.set
|
|
100
|
+
mapping: {
|
|
101
|
+
product: {
|
|
102
|
+
view: {
|
|
103
|
+
settings: {
|
|
104
|
+
set: {
|
|
105
|
+
map: {
|
|
106
|
+
product_color: 'data.color',
|
|
107
|
+
product_id: 'data.id',
|
|
108
|
+
},
|
|
109
|
+
},
|
|
110
|
+
},
|
|
111
|
+
},
|
|
112
|
+
},
|
|
113
|
+
}
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
## Consent Translation
|
|
117
|
+
|
|
118
|
+
Clarity expects its own category names (`analytics_Storage`, `ad_Storage`).
|
|
119
|
+
walkerOS uses arbitrary consent keys, so translation is explicit — no magic
|
|
120
|
+
defaults. Configure `settings.consent` once and the destination handles
|
|
121
|
+
`walker consent` events automatically:
|
|
122
|
+
|
|
123
|
+
```typescript
|
|
124
|
+
settings: {
|
|
125
|
+
apiKey: '3t0wlogvdz',
|
|
126
|
+
consent: {
|
|
127
|
+
analytics: 'analytics_Storage',
|
|
128
|
+
marketing: 'ad_Storage',
|
|
129
|
+
},
|
|
130
|
+
}
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
All consent state — grants, revocations, partial updates — is forwarded to
|
|
134
|
+
`Clarity.consentV2(...)`. The legacy `Clarity.consent(...)` API is not used.
|
|
135
|
+
Without `settings.consent`, the destination takes no action on consent changes;
|
|
136
|
+
the walkerOS `config.consent` gate still blocks unconsented events from reaching
|
|
137
|
+
the destination in the first place.
|
|
138
|
+
|
|
139
|
+
## Contribute
|
|
140
|
+
|
|
141
|
+
Feel free to contribute by submitting an
|
|
142
|
+
[issue](https://github.com/elbwalker/walkerOS/issues), starting a
|
|
143
|
+
[discussion](https://github.com/elbwalker/walkerOS/discussions), or getting in
|
|
144
|
+
[contact](https://calendly.com/elb-alexander/30min).
|
|
145
|
+
|
|
146
|
+
## License
|
|
147
|
+
|
|
148
|
+
This project is licensed under the MIT License.
|
package/dist/dev.d.mts
ADDED
|
@@ -0,0 +1,206 @@
|
|
|
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
|
+
|
|
6
|
+
declare const SettingsSchema: z.ZodObject<{
|
|
7
|
+
apiKey: z.ZodString;
|
|
8
|
+
consent: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
|
|
9
|
+
analytics_Storage: "analytics_Storage";
|
|
10
|
+
ad_Storage: "ad_Storage";
|
|
11
|
+
}>>>;
|
|
12
|
+
identify: z.ZodOptional<z.ZodUnknown>;
|
|
13
|
+
}, z.core.$strip>;
|
|
14
|
+
type Settings$1 = z.infer<typeof SettingsSchema>;
|
|
15
|
+
|
|
16
|
+
declare const MappingSchema: z.ZodObject<{
|
|
17
|
+
identify: z.ZodOptional<z.ZodUnknown>;
|
|
18
|
+
set: z.ZodOptional<z.ZodUnknown>;
|
|
19
|
+
upgrade: z.ZodOptional<z.ZodUnknown>;
|
|
20
|
+
}, z.core.$strip>;
|
|
21
|
+
type Mapping = z.infer<typeof MappingSchema>;
|
|
22
|
+
|
|
23
|
+
declare const settings: _walkeros_core_dev.JSONSchema;
|
|
24
|
+
declare const mapping: _walkeros_core_dev.JSONSchema;
|
|
25
|
+
|
|
26
|
+
type index$1_Mapping = Mapping;
|
|
27
|
+
declare const index$1_MappingSchema: typeof MappingSchema;
|
|
28
|
+
declare const index$1_SettingsSchema: typeof SettingsSchema;
|
|
29
|
+
declare const index$1_mapping: typeof mapping;
|
|
30
|
+
declare const index$1_settings: typeof settings;
|
|
31
|
+
declare namespace index$1 {
|
|
32
|
+
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 };
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* Settings (destination-level).
|
|
37
|
+
*
|
|
38
|
+
* apiKey is the Clarity project ID (e.g. "3t0wlogvdz").
|
|
39
|
+
* consent translates walkerOS consent keys to Clarity's ConsentV2 categories.
|
|
40
|
+
* identify resolves to positional args for Clarity.identify(...).
|
|
41
|
+
*/
|
|
42
|
+
interface Settings {
|
|
43
|
+
apiKey: string;
|
|
44
|
+
consent?: Record<string, 'analytics_Storage' | 'ad_Storage'>;
|
|
45
|
+
identify?: Mapping$1.Value;
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* Clarity SDK surface — the subset of @microsoft/clarity methods this
|
|
49
|
+
* destination actually uses. Mirrors the default export so tests can mock
|
|
50
|
+
* each method individually. The legacy `consent()` API is intentionally
|
|
51
|
+
* not exposed here — this destination only uses `consentV2`.
|
|
52
|
+
*/
|
|
53
|
+
interface ClaritySDK {
|
|
54
|
+
init: (projectId: string) => void;
|
|
55
|
+
identify: (customId: string, customSessionId?: string, customPageId?: string, friendlyName?: string) => void;
|
|
56
|
+
setTag: (key: string, value: string | string[]) => void;
|
|
57
|
+
event: (name: string) => void;
|
|
58
|
+
consentV2: (consentOptions?: {
|
|
59
|
+
ad_Storage: 'granted' | 'denied';
|
|
60
|
+
analytics_Storage: 'granted' | 'denied';
|
|
61
|
+
}) => void;
|
|
62
|
+
upgrade: (reason: string) => void;
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* Env — optional override for the vendor SDK. Production leaves this
|
|
66
|
+
* undefined and the destination falls back to the real `@microsoft/clarity`
|
|
67
|
+
* default export. Tests provide a mock via `env.clarity = { ... }`.
|
|
68
|
+
*/
|
|
69
|
+
interface Env extends DestinationWeb.Env {
|
|
70
|
+
clarity?: ClaritySDK;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* Pre-init environment — Clarity SDK methods are no-ops until init wires them.
|
|
75
|
+
*/
|
|
76
|
+
declare const init: Env | undefined;
|
|
77
|
+
/**
|
|
78
|
+
* Post-init environment — Clarity SDK methods are spy-able no-ops.
|
|
79
|
+
* Tests clone this and replace individual methods with jest.fn() for assertions.
|
|
80
|
+
*/
|
|
81
|
+
declare const push: Env;
|
|
82
|
+
/**
|
|
83
|
+
* Simulation tracking paths for CLI --simulate
|
|
84
|
+
*/
|
|
85
|
+
declare const simulation: string[];
|
|
86
|
+
|
|
87
|
+
declare const env_init: typeof init;
|
|
88
|
+
declare const env_push: typeof push;
|
|
89
|
+
declare const env_simulation: typeof simulation;
|
|
90
|
+
declare namespace env {
|
|
91
|
+
export { env_init as init, env_push as push, env_simulation as simulation };
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/**
|
|
95
|
+
* Examples may optionally override destination-level settings for a test.
|
|
96
|
+
* The test runner reads `settings` from the example and merges it into the
|
|
97
|
+
* base destination settings (on top of the fixed `apiKey`). `configInclude`
|
|
98
|
+
* is passed as config-level include when registering the destination.
|
|
99
|
+
*/
|
|
100
|
+
type ClarityStepExample = Flow.StepExample & {
|
|
101
|
+
settings?: Partial<Settings>;
|
|
102
|
+
configInclude?: string[];
|
|
103
|
+
};
|
|
104
|
+
/**
|
|
105
|
+
* Default event forwarding — every walkerOS event becomes Clarity.event(name).
|
|
106
|
+
* No mapping rule; the destination's default push behavior fires.
|
|
107
|
+
*/
|
|
108
|
+
declare const defaultEventForwarding: ClarityStepExample;
|
|
109
|
+
/**
|
|
110
|
+
* Wildcard ignore pattern — the standard walkerOS way to suppress noisy events.
|
|
111
|
+
* The destination forwards by default; users opt OUT via `"*": { "*": { ignore: true } }`
|
|
112
|
+
* plus explicit allows. This example IS an ignored event — the destination
|
|
113
|
+
* must produce zero calls.
|
|
114
|
+
*/
|
|
115
|
+
declare const wildcardIgnored: ClarityStepExample;
|
|
116
|
+
/**
|
|
117
|
+
* Identity via settings.identify (per-event, user login).
|
|
118
|
+
* Resolves positional args for Clarity.identify(customId, sessionId, pageId, friendlyName).
|
|
119
|
+
* Trailing undefined args are omitted, so all four args are passed when friendlyName is set.
|
|
120
|
+
* Then fires the default Clarity.event(...) forwarding.
|
|
121
|
+
*/
|
|
122
|
+
declare const userLoginIdentify: ClarityStepExample;
|
|
123
|
+
/**
|
|
124
|
+
* Destination-level settings.identify — Clarity officially recommends calling
|
|
125
|
+
* identify() on every page load. walkerOS expresses this via destination-level
|
|
126
|
+
* `settings.identify`, which fires on every push.
|
|
127
|
+
*/
|
|
128
|
+
declare const destinationLevelIdentify: ClarityStepExample;
|
|
129
|
+
/**
|
|
130
|
+
* Explicit custom tags via mapping.settings.set.
|
|
131
|
+
* Each resolved key → Clarity.setTag(key, value). Tags fire after identify
|
|
132
|
+
* but before the default event.
|
|
133
|
+
*/
|
|
134
|
+
declare const productViewWithTags: ClarityStepExample;
|
|
135
|
+
/**
|
|
136
|
+
* Array tag values — Clarity.setTag(key, value) natively accepts string[].
|
|
137
|
+
* walkerOS array values are passed through unchanged (each element is
|
|
138
|
+
* coerced to string, but the array shape is preserved — no flattening,
|
|
139
|
+
* no splitting into multiple calls).
|
|
140
|
+
*/
|
|
141
|
+
declare const arrayTagValue: ClarityStepExample;
|
|
142
|
+
/**
|
|
143
|
+
* Session priority upgrade — mark this session as important so Clarity retains
|
|
144
|
+
* it beyond the sampling cap. upgrade fires before the default event.
|
|
145
|
+
*/
|
|
146
|
+
declare const orderCompleteUpgrade: ClarityStepExample;
|
|
147
|
+
/**
|
|
148
|
+
* settings.include flattens a walkerOS event section into Clarity.setTag calls.
|
|
149
|
+
* Primitives coerce to strings; arrays pass through as string[].
|
|
150
|
+
* The example includes `data` only; keys become `data_<field>`.
|
|
151
|
+
*/
|
|
152
|
+
declare const orderCompleteInclude: ClarityStepExample;
|
|
153
|
+
/**
|
|
154
|
+
* Combined-feature rule — Clarity's canonical usage pattern: identify the
|
|
155
|
+
* user, set session tags, upgrade session priority, then fire the event.
|
|
156
|
+
* This is the authoritative test for the push execution order
|
|
157
|
+
* (identify → tags → upgrade → event).
|
|
158
|
+
*/
|
|
159
|
+
declare const combinedFeatures: ClarityStepExample;
|
|
160
|
+
/**
|
|
161
|
+
* mapping.skip — the rule runs (set/identify/upgrade all execute) but the
|
|
162
|
+
* default Clarity.event(...) call is suppressed. Useful for page view, where
|
|
163
|
+
* Clarity has its own page tracking and you only want to set tags.
|
|
164
|
+
*/
|
|
165
|
+
declare const pageViewSkip: ClarityStepExample;
|
|
166
|
+
/**
|
|
167
|
+
* Consent translation via settings.consent.
|
|
168
|
+
* walkerOS consent { analytics: true, marketing: true } with the mapping
|
|
169
|
+
* { analytics: 'analytics_Storage', marketing: 'ad_Storage' } fires:
|
|
170
|
+
* Clarity.consentV2({ analytics_Storage: 'granted', ad_Storage: 'granted' })
|
|
171
|
+
*
|
|
172
|
+
* Uses the canonical StepExample.command='consent' pattern: the test runner
|
|
173
|
+
* dispatches via elb('walker consent', in) instead of pushing an event.
|
|
174
|
+
*/
|
|
175
|
+
declare const consentGrantBoth: ClarityStepExample;
|
|
176
|
+
/**
|
|
177
|
+
* Consent revocation — denied categories call Clarity.consentV2(...) with
|
|
178
|
+
* denied flags. The destination does NOT call the legacy `Clarity.consent(false)`
|
|
179
|
+
* API at all — consentV2 is the single source of truth for consent state.
|
|
180
|
+
*/
|
|
181
|
+
declare const consentRevoke: ClarityStepExample;
|
|
182
|
+
|
|
183
|
+
type step_ClarityStepExample = ClarityStepExample;
|
|
184
|
+
declare const step_arrayTagValue: typeof arrayTagValue;
|
|
185
|
+
declare const step_combinedFeatures: typeof combinedFeatures;
|
|
186
|
+
declare const step_consentGrantBoth: typeof consentGrantBoth;
|
|
187
|
+
declare const step_consentRevoke: typeof consentRevoke;
|
|
188
|
+
declare const step_defaultEventForwarding: typeof defaultEventForwarding;
|
|
189
|
+
declare const step_destinationLevelIdentify: typeof destinationLevelIdentify;
|
|
190
|
+
declare const step_orderCompleteInclude: typeof orderCompleteInclude;
|
|
191
|
+
declare const step_orderCompleteUpgrade: typeof orderCompleteUpgrade;
|
|
192
|
+
declare const step_pageViewSkip: typeof pageViewSkip;
|
|
193
|
+
declare const step_productViewWithTags: typeof productViewWithTags;
|
|
194
|
+
declare const step_userLoginIdentify: typeof userLoginIdentify;
|
|
195
|
+
declare const step_wildcardIgnored: typeof wildcardIgnored;
|
|
196
|
+
declare namespace step {
|
|
197
|
+
export { type step_ClarityStepExample as ClarityStepExample, step_arrayTagValue as arrayTagValue, step_combinedFeatures as combinedFeatures, step_consentGrantBoth as consentGrantBoth, step_consentRevoke as consentRevoke, step_defaultEventForwarding as defaultEventForwarding, step_destinationLevelIdentify as destinationLevelIdentify, step_orderCompleteInclude as orderCompleteInclude, step_orderCompleteUpgrade as orderCompleteUpgrade, step_pageViewSkip as pageViewSkip, step_productViewWithTags as productViewWithTags, step_userLoginIdentify as userLoginIdentify, step_wildcardIgnored as wildcardIgnored };
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
declare const index_env: typeof env;
|
|
201
|
+
declare const index_step: typeof step;
|
|
202
|
+
declare namespace index {
|
|
203
|
+
export { index_env as env, index_step as step };
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
export { index as examples, index$1 as schemas };
|
package/dist/dev.d.ts
ADDED
|
@@ -0,0 +1,206 @@
|
|
|
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
|
+
|
|
6
|
+
declare const SettingsSchema: z.ZodObject<{
|
|
7
|
+
apiKey: z.ZodString;
|
|
8
|
+
consent: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
|
|
9
|
+
analytics_Storage: "analytics_Storage";
|
|
10
|
+
ad_Storage: "ad_Storage";
|
|
11
|
+
}>>>;
|
|
12
|
+
identify: z.ZodOptional<z.ZodUnknown>;
|
|
13
|
+
}, z.core.$strip>;
|
|
14
|
+
type Settings$1 = z.infer<typeof SettingsSchema>;
|
|
15
|
+
|
|
16
|
+
declare const MappingSchema: z.ZodObject<{
|
|
17
|
+
identify: z.ZodOptional<z.ZodUnknown>;
|
|
18
|
+
set: z.ZodOptional<z.ZodUnknown>;
|
|
19
|
+
upgrade: z.ZodOptional<z.ZodUnknown>;
|
|
20
|
+
}, z.core.$strip>;
|
|
21
|
+
type Mapping = z.infer<typeof MappingSchema>;
|
|
22
|
+
|
|
23
|
+
declare const settings: _walkeros_core_dev.JSONSchema;
|
|
24
|
+
declare const mapping: _walkeros_core_dev.JSONSchema;
|
|
25
|
+
|
|
26
|
+
type index$1_Mapping = Mapping;
|
|
27
|
+
declare const index$1_MappingSchema: typeof MappingSchema;
|
|
28
|
+
declare const index$1_SettingsSchema: typeof SettingsSchema;
|
|
29
|
+
declare const index$1_mapping: typeof mapping;
|
|
30
|
+
declare const index$1_settings: typeof settings;
|
|
31
|
+
declare namespace index$1 {
|
|
32
|
+
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 };
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* Settings (destination-level).
|
|
37
|
+
*
|
|
38
|
+
* apiKey is the Clarity project ID (e.g. "3t0wlogvdz").
|
|
39
|
+
* consent translates walkerOS consent keys to Clarity's ConsentV2 categories.
|
|
40
|
+
* identify resolves to positional args for Clarity.identify(...).
|
|
41
|
+
*/
|
|
42
|
+
interface Settings {
|
|
43
|
+
apiKey: string;
|
|
44
|
+
consent?: Record<string, 'analytics_Storage' | 'ad_Storage'>;
|
|
45
|
+
identify?: Mapping$1.Value;
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* Clarity SDK surface — the subset of @microsoft/clarity methods this
|
|
49
|
+
* destination actually uses. Mirrors the default export so tests can mock
|
|
50
|
+
* each method individually. The legacy `consent()` API is intentionally
|
|
51
|
+
* not exposed here — this destination only uses `consentV2`.
|
|
52
|
+
*/
|
|
53
|
+
interface ClaritySDK {
|
|
54
|
+
init: (projectId: string) => void;
|
|
55
|
+
identify: (customId: string, customSessionId?: string, customPageId?: string, friendlyName?: string) => void;
|
|
56
|
+
setTag: (key: string, value: string | string[]) => void;
|
|
57
|
+
event: (name: string) => void;
|
|
58
|
+
consentV2: (consentOptions?: {
|
|
59
|
+
ad_Storage: 'granted' | 'denied';
|
|
60
|
+
analytics_Storage: 'granted' | 'denied';
|
|
61
|
+
}) => void;
|
|
62
|
+
upgrade: (reason: string) => void;
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* Env — optional override for the vendor SDK. Production leaves this
|
|
66
|
+
* undefined and the destination falls back to the real `@microsoft/clarity`
|
|
67
|
+
* default export. Tests provide a mock via `env.clarity = { ... }`.
|
|
68
|
+
*/
|
|
69
|
+
interface Env extends DestinationWeb.Env {
|
|
70
|
+
clarity?: ClaritySDK;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* Pre-init environment — Clarity SDK methods are no-ops until init wires them.
|
|
75
|
+
*/
|
|
76
|
+
declare const init: Env | undefined;
|
|
77
|
+
/**
|
|
78
|
+
* Post-init environment — Clarity SDK methods are spy-able no-ops.
|
|
79
|
+
* Tests clone this and replace individual methods with jest.fn() for assertions.
|
|
80
|
+
*/
|
|
81
|
+
declare const push: Env;
|
|
82
|
+
/**
|
|
83
|
+
* Simulation tracking paths for CLI --simulate
|
|
84
|
+
*/
|
|
85
|
+
declare const simulation: string[];
|
|
86
|
+
|
|
87
|
+
declare const env_init: typeof init;
|
|
88
|
+
declare const env_push: typeof push;
|
|
89
|
+
declare const env_simulation: typeof simulation;
|
|
90
|
+
declare namespace env {
|
|
91
|
+
export { env_init as init, env_push as push, env_simulation as simulation };
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/**
|
|
95
|
+
* Examples may optionally override destination-level settings for a test.
|
|
96
|
+
* The test runner reads `settings` from the example and merges it into the
|
|
97
|
+
* base destination settings (on top of the fixed `apiKey`). `configInclude`
|
|
98
|
+
* is passed as config-level include when registering the destination.
|
|
99
|
+
*/
|
|
100
|
+
type ClarityStepExample = Flow.StepExample & {
|
|
101
|
+
settings?: Partial<Settings>;
|
|
102
|
+
configInclude?: string[];
|
|
103
|
+
};
|
|
104
|
+
/**
|
|
105
|
+
* Default event forwarding — every walkerOS event becomes Clarity.event(name).
|
|
106
|
+
* No mapping rule; the destination's default push behavior fires.
|
|
107
|
+
*/
|
|
108
|
+
declare const defaultEventForwarding: ClarityStepExample;
|
|
109
|
+
/**
|
|
110
|
+
* Wildcard ignore pattern — the standard walkerOS way to suppress noisy events.
|
|
111
|
+
* The destination forwards by default; users opt OUT via `"*": { "*": { ignore: true } }`
|
|
112
|
+
* plus explicit allows. This example IS an ignored event — the destination
|
|
113
|
+
* must produce zero calls.
|
|
114
|
+
*/
|
|
115
|
+
declare const wildcardIgnored: ClarityStepExample;
|
|
116
|
+
/**
|
|
117
|
+
* Identity via settings.identify (per-event, user login).
|
|
118
|
+
* Resolves positional args for Clarity.identify(customId, sessionId, pageId, friendlyName).
|
|
119
|
+
* Trailing undefined args are omitted, so all four args are passed when friendlyName is set.
|
|
120
|
+
* Then fires the default Clarity.event(...) forwarding.
|
|
121
|
+
*/
|
|
122
|
+
declare const userLoginIdentify: ClarityStepExample;
|
|
123
|
+
/**
|
|
124
|
+
* Destination-level settings.identify — Clarity officially recommends calling
|
|
125
|
+
* identify() on every page load. walkerOS expresses this via destination-level
|
|
126
|
+
* `settings.identify`, which fires on every push.
|
|
127
|
+
*/
|
|
128
|
+
declare const destinationLevelIdentify: ClarityStepExample;
|
|
129
|
+
/**
|
|
130
|
+
* Explicit custom tags via mapping.settings.set.
|
|
131
|
+
* Each resolved key → Clarity.setTag(key, value). Tags fire after identify
|
|
132
|
+
* but before the default event.
|
|
133
|
+
*/
|
|
134
|
+
declare const productViewWithTags: ClarityStepExample;
|
|
135
|
+
/**
|
|
136
|
+
* Array tag values — Clarity.setTag(key, value) natively accepts string[].
|
|
137
|
+
* walkerOS array values are passed through unchanged (each element is
|
|
138
|
+
* coerced to string, but the array shape is preserved — no flattening,
|
|
139
|
+
* no splitting into multiple calls).
|
|
140
|
+
*/
|
|
141
|
+
declare const arrayTagValue: ClarityStepExample;
|
|
142
|
+
/**
|
|
143
|
+
* Session priority upgrade — mark this session as important so Clarity retains
|
|
144
|
+
* it beyond the sampling cap. upgrade fires before the default event.
|
|
145
|
+
*/
|
|
146
|
+
declare const orderCompleteUpgrade: ClarityStepExample;
|
|
147
|
+
/**
|
|
148
|
+
* settings.include flattens a walkerOS event section into Clarity.setTag calls.
|
|
149
|
+
* Primitives coerce to strings; arrays pass through as string[].
|
|
150
|
+
* The example includes `data` only; keys become `data_<field>`.
|
|
151
|
+
*/
|
|
152
|
+
declare const orderCompleteInclude: ClarityStepExample;
|
|
153
|
+
/**
|
|
154
|
+
* Combined-feature rule — Clarity's canonical usage pattern: identify the
|
|
155
|
+
* user, set session tags, upgrade session priority, then fire the event.
|
|
156
|
+
* This is the authoritative test for the push execution order
|
|
157
|
+
* (identify → tags → upgrade → event).
|
|
158
|
+
*/
|
|
159
|
+
declare const combinedFeatures: ClarityStepExample;
|
|
160
|
+
/**
|
|
161
|
+
* mapping.skip — the rule runs (set/identify/upgrade all execute) but the
|
|
162
|
+
* default Clarity.event(...) call is suppressed. Useful for page view, where
|
|
163
|
+
* Clarity has its own page tracking and you only want to set tags.
|
|
164
|
+
*/
|
|
165
|
+
declare const pageViewSkip: ClarityStepExample;
|
|
166
|
+
/**
|
|
167
|
+
* Consent translation via settings.consent.
|
|
168
|
+
* walkerOS consent { analytics: true, marketing: true } with the mapping
|
|
169
|
+
* { analytics: 'analytics_Storage', marketing: 'ad_Storage' } fires:
|
|
170
|
+
* Clarity.consentV2({ analytics_Storage: 'granted', ad_Storage: 'granted' })
|
|
171
|
+
*
|
|
172
|
+
* Uses the canonical StepExample.command='consent' pattern: the test runner
|
|
173
|
+
* dispatches via elb('walker consent', in) instead of pushing an event.
|
|
174
|
+
*/
|
|
175
|
+
declare const consentGrantBoth: ClarityStepExample;
|
|
176
|
+
/**
|
|
177
|
+
* Consent revocation — denied categories call Clarity.consentV2(...) with
|
|
178
|
+
* denied flags. The destination does NOT call the legacy `Clarity.consent(false)`
|
|
179
|
+
* API at all — consentV2 is the single source of truth for consent state.
|
|
180
|
+
*/
|
|
181
|
+
declare const consentRevoke: ClarityStepExample;
|
|
182
|
+
|
|
183
|
+
type step_ClarityStepExample = ClarityStepExample;
|
|
184
|
+
declare const step_arrayTagValue: typeof arrayTagValue;
|
|
185
|
+
declare const step_combinedFeatures: typeof combinedFeatures;
|
|
186
|
+
declare const step_consentGrantBoth: typeof consentGrantBoth;
|
|
187
|
+
declare const step_consentRevoke: typeof consentRevoke;
|
|
188
|
+
declare const step_defaultEventForwarding: typeof defaultEventForwarding;
|
|
189
|
+
declare const step_destinationLevelIdentify: typeof destinationLevelIdentify;
|
|
190
|
+
declare const step_orderCompleteInclude: typeof orderCompleteInclude;
|
|
191
|
+
declare const step_orderCompleteUpgrade: typeof orderCompleteUpgrade;
|
|
192
|
+
declare const step_pageViewSkip: typeof pageViewSkip;
|
|
193
|
+
declare const step_productViewWithTags: typeof productViewWithTags;
|
|
194
|
+
declare const step_userLoginIdentify: typeof userLoginIdentify;
|
|
195
|
+
declare const step_wildcardIgnored: typeof wildcardIgnored;
|
|
196
|
+
declare namespace step {
|
|
197
|
+
export { type step_ClarityStepExample as ClarityStepExample, step_arrayTagValue as arrayTagValue, step_combinedFeatures as combinedFeatures, step_consentGrantBoth as consentGrantBoth, step_consentRevoke as consentRevoke, step_defaultEventForwarding as defaultEventForwarding, step_destinationLevelIdentify as destinationLevelIdentify, step_orderCompleteInclude as orderCompleteInclude, step_orderCompleteUpgrade as orderCompleteUpgrade, step_pageViewSkip as pageViewSkip, step_productViewWithTags as productViewWithTags, step_userLoginIdentify as userLoginIdentify, step_wildcardIgnored as wildcardIgnored };
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
declare const index_env: typeof env;
|
|
201
|
+
declare const index_step: typeof step;
|
|
202
|
+
declare namespace index {
|
|
203
|
+
export { index_env as env, index_step as step };
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
export { index as examples, index$1 as schemas };
|