@walkeros/web-destination-posthog 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 +308 -0
- package/dist/dev.d.mts +269 -0
- package/dist/dev.d.ts +269 -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 +206 -0
- package/dist/examples/index.d.ts +206 -0
- package/dist/examples/index.js +14439 -0
- package/dist/examples/index.mjs +14417 -0
- package/dist/index.browser.js +1 -0
- package/dist/index.d.mts +112 -0
- package/dist/index.d.ts +112 -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 +1096 -0
- package/package.json +79 -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,308 @@
|
|
|
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
|
+
# PostHog Destination for walkerOS
|
|
8
|
+
|
|
9
|
+
[Source Code](https://github.com/elbwalker/walkerOS/tree/main/packages/web/destinations/posthog)
|
|
10
|
+
•
|
|
11
|
+
[NPM Package](https://www.npmjs.com/package/@walkeros/web-destination-posthog)
|
|
12
|
+
• [Documentation](https://www.walkeros.io/docs/destinations/web/posthog)
|
|
13
|
+
|
|
14
|
+
This package forwards walkerOS events to [PostHog](https://posthog.com/) —
|
|
15
|
+
product analytics, session replay, feature flags, surveys, and heatmaps. Built
|
|
16
|
+
on the official [`posthog-js`](https://www.npmjs.com/package/posthog-js) SDK.
|
|
17
|
+
|
|
18
|
+
walkerOS follows a **source → collector → destination** architecture. This
|
|
19
|
+
PostHog destination receives processed events from the walkerOS collector and
|
|
20
|
+
forwards them as PostHog captures, identifies, group assignments, and consent
|
|
21
|
+
updates. All built-in PostHog features (session replay, feature flags, surveys,
|
|
22
|
+
heatmaps, exception capture) are available through SDK init passthrough — no
|
|
23
|
+
destination-specific plugins required.
|
|
24
|
+
|
|
25
|
+
## Features
|
|
26
|
+
|
|
27
|
+
- **Default event forwarding** — every walkerOS event becomes
|
|
28
|
+
`posthog.capture(event.name, properties)` with no additional config
|
|
29
|
+
- **Custom event properties** — flatten walkerOS event sections via
|
|
30
|
+
`settings.include` (prefixed as `data_*`, `globals_*`, etc.)
|
|
31
|
+
- **Identity** — destination-level and per-event identity mapping resolving to
|
|
32
|
+
`{ distinctId?, $set?, $set_once? }`. With `distinctId`: `posthog.identify()`.
|
|
33
|
+
Without `distinctId`: `posthog.setPersonProperties()` for pure person-property
|
|
34
|
+
updates. Runtime state diffing skips redundant identify calls when the
|
|
35
|
+
resolved values have not changed.
|
|
36
|
+
- **Groups** — B2B-style group analytics via `settings.group`; resolves to
|
|
37
|
+
`{ type, key, properties? }` and calls `posthog.group(...)`
|
|
38
|
+
- **Logout** — `reset: true` triggers `posthog.reset()` to clear the distinct ID
|
|
39
|
+
and regenerate an anonymous one
|
|
40
|
+
- **Consent** — declares required consent keys via `config.consent`; a
|
|
41
|
+
`walker consent` event with all required keys granted calls
|
|
42
|
+
`posthog.opt_in_capturing()`, otherwise `posthog.opt_out_capturing()`
|
|
43
|
+
- **Built-in PostHog features as config passthrough** — session replay
|
|
44
|
+
(`session_recording`), feature flags (`bootstrap`, `advanced_disable_flags`),
|
|
45
|
+
surveys (`disable_surveys`), heatmaps (`capture_heatmaps`), exception capture
|
|
46
|
+
(`capture_exceptions`), cookieless mode (`cookieless_mode`). All
|
|
47
|
+
`PostHogConfig` fields pass through unchanged.
|
|
48
|
+
|
|
49
|
+
## Installation
|
|
50
|
+
|
|
51
|
+
```sh
|
|
52
|
+
npm install @walkeros/web-destination-posthog
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
## Quick Start
|
|
56
|
+
|
|
57
|
+
```typescript
|
|
58
|
+
import { startFlow } from '@walkeros/collector';
|
|
59
|
+
import { destinationPostHog } from '@walkeros/web-destination-posthog';
|
|
60
|
+
|
|
61
|
+
await startFlow({
|
|
62
|
+
destinations: {
|
|
63
|
+
posthog: {
|
|
64
|
+
code: destinationPostHog,
|
|
65
|
+
config: {
|
|
66
|
+
settings: {
|
|
67
|
+
apiKey: 'phc_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
|
|
68
|
+
api_host: 'https://eu.i.posthog.com', // or us.i.posthog.com
|
|
69
|
+
},
|
|
70
|
+
},
|
|
71
|
+
},
|
|
72
|
+
},
|
|
73
|
+
});
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## Configuration
|
|
77
|
+
|
|
78
|
+
### Settings (destination-level)
|
|
79
|
+
|
|
80
|
+
| Name | Type | Description | Required |
|
|
81
|
+
| ---------- | --------------- | -------------------------------------------------------------------------------------------------- | -------- |
|
|
82
|
+
| `apiKey` | `string` | PostHog project API key (starts with `phc_`) | Yes |
|
|
83
|
+
| `api_host` | `string` | PostHog ingestion host. Default `https://us.i.posthog.com`. Use `https://eu.i.posthog.com` for EU. | No |
|
|
84
|
+
| `include` | `string[]` | walkerOS event sections to flatten into `capture()` properties (`data`, `globals`, `context`, …) | No |
|
|
85
|
+
| `identify` | `Mapping.Value` | Destination-level identity mapping; resolves to `{ distinctId?, $set?, $set_once? }` | No |
|
|
86
|
+
| `group` | `Mapping.Value` | Destination-level group assignment; resolves to `{ type, key, properties? }` | No |
|
|
87
|
+
|
|
88
|
+
All other [`PostHogConfig`](https://posthog.com/docs/libraries/js#config) fields
|
|
89
|
+
(e.g. `session_recording`, `capture_heatmaps`, `bootstrap`, `cookieless_mode`)
|
|
90
|
+
pass through unchanged. walkerOS sets three defaults that differ from PostHog's
|
|
91
|
+
built-ins: `autocapture: false`, `capture_pageview: false`,
|
|
92
|
+
`capture_pageleave: false` — because walkerOS sources handle event capture.
|
|
93
|
+
Override them explicitly in `settings` if you want PostHog's autocapture on.
|
|
94
|
+
|
|
95
|
+
### Mapping (`rule.settings`)
|
|
96
|
+
|
|
97
|
+
| Name | Type | Description |
|
|
98
|
+
| ---------- | -------------------------- | ------------------------------------------------------------------------------------- |
|
|
99
|
+
| `identify` | `Mapping.Value` | Per-event identity. Resolves to `{ distinctId?, $set?, $set_once? }` |
|
|
100
|
+
| `include` | `string[]` | Override destination-level `include` for this rule |
|
|
101
|
+
| `group` | `Mapping.Value` | Per-event group assignment. Resolves to `{ type, key, properties? }` |
|
|
102
|
+
| `reset` | `Mapping.Value \| boolean` | Logout trigger. Truthy value → `posthog.reset()`. Typically paired with `skip: true`. |
|
|
103
|
+
|
|
104
|
+
## Custom Event Properties
|
|
105
|
+
|
|
106
|
+
Two ways to attach properties to a PostHog capture:
|
|
107
|
+
|
|
108
|
+
```typescript
|
|
109
|
+
// 1. Flatten walkerOS sections with settings.include
|
|
110
|
+
config: {
|
|
111
|
+
settings: {
|
|
112
|
+
apiKey: 'phc_...',
|
|
113
|
+
include: ['data', 'globals'], // → data_*, globals_* on every event
|
|
114
|
+
},
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
// 2. Override per-rule via mapping.settings.include
|
|
118
|
+
mapping: {
|
|
119
|
+
order: {
|
|
120
|
+
complete: {
|
|
121
|
+
settings: {
|
|
122
|
+
include: ['data', 'globals'], // EUR currency, totals, pagegroup
|
|
123
|
+
},
|
|
124
|
+
},
|
|
125
|
+
},
|
|
126
|
+
}
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
PostHog has no dedicated revenue API — revenue events are regular `capture()`
|
|
130
|
+
calls with the revenue properties in the payload. Use `include: ['data']` on an
|
|
131
|
+
`order complete` rule to forward `data_total`, `data_currency` (e.g. `"EUR"`),
|
|
132
|
+
`data_shipping`, etc.
|
|
133
|
+
|
|
134
|
+
## Identity
|
|
135
|
+
|
|
136
|
+
Destination-level identify fires on the first push and re-fires only when the
|
|
137
|
+
resolved `distinctId` changes (runtime state diffing, skip redundant calls):
|
|
138
|
+
|
|
139
|
+
```typescript
|
|
140
|
+
settings: {
|
|
141
|
+
apiKey: 'phc_...',
|
|
142
|
+
identify: {
|
|
143
|
+
map: {
|
|
144
|
+
distinctId: 'user.id',
|
|
145
|
+
},
|
|
146
|
+
},
|
|
147
|
+
}
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
Per-event identify supports the full PostHog vocabulary — `distinctId`, `$set`
|
|
151
|
+
(person properties), `$set_once` (set-if-unset person properties). The
|
|
152
|
+
destination calls `posthog.identify(distinctId, $set, $set_once)`:
|
|
153
|
+
|
|
154
|
+
```typescript
|
|
155
|
+
mapping: {
|
|
156
|
+
user: {
|
|
157
|
+
login: {
|
|
158
|
+
skip: true, // side-effect only, no capture() for user login
|
|
159
|
+
settings: {
|
|
160
|
+
identify: {
|
|
161
|
+
map: {
|
|
162
|
+
distinctId: 'data.user_id',
|
|
163
|
+
$set: {
|
|
164
|
+
map: {
|
|
165
|
+
email: 'data.email',
|
|
166
|
+
plan: 'data.plan',
|
|
167
|
+
},
|
|
168
|
+
},
|
|
169
|
+
$set_once: {
|
|
170
|
+
map: { first_login: 'timestamp' },
|
|
171
|
+
},
|
|
172
|
+
},
|
|
173
|
+
},
|
|
174
|
+
},
|
|
175
|
+
},
|
|
176
|
+
},
|
|
177
|
+
}
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
**Person properties without identity change.** When the resolved identify object
|
|
181
|
+
has no `distinctId`, the destination calls
|
|
182
|
+
`posthog.setPersonProperties($set, $set_once)` instead — useful for profile
|
|
183
|
+
updates that should not create a new identity:
|
|
184
|
+
|
|
185
|
+
```typescript
|
|
186
|
+
mapping: {
|
|
187
|
+
profile: {
|
|
188
|
+
update: {
|
|
189
|
+
settings: {
|
|
190
|
+
identify: {
|
|
191
|
+
map: {
|
|
192
|
+
$set: { map: { name: 'data.name' } },
|
|
193
|
+
},
|
|
194
|
+
},
|
|
195
|
+
},
|
|
196
|
+
},
|
|
197
|
+
},
|
|
198
|
+
}
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
## Groups
|
|
202
|
+
|
|
203
|
+
PostHog's group analytics (Scale/Enterprise) aggregates events by company, team,
|
|
204
|
+
or any custom group type. Configure a group mapping at destination or rule level
|
|
205
|
+
— the destination calls `posthog.group(type, key, properties?)`:
|
|
206
|
+
|
|
207
|
+
```typescript
|
|
208
|
+
mapping: {
|
|
209
|
+
company: {
|
|
210
|
+
update: {
|
|
211
|
+
skip: true,
|
|
212
|
+
settings: {
|
|
213
|
+
group: {
|
|
214
|
+
map: {
|
|
215
|
+
type: { value: 'company' },
|
|
216
|
+
key: 'data.company_id',
|
|
217
|
+
properties: {
|
|
218
|
+
map: {
|
|
219
|
+
name: 'data.company_name',
|
|
220
|
+
plan: 'data.plan',
|
|
221
|
+
},
|
|
222
|
+
},
|
|
223
|
+
},
|
|
224
|
+
},
|
|
225
|
+
},
|
|
226
|
+
},
|
|
227
|
+
},
|
|
228
|
+
}
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
## Logout
|
|
232
|
+
|
|
233
|
+
`reset: true` (or any truthy mapping value) calls `posthog.reset()`, clearing
|
|
234
|
+
the distinct ID and generating a new anonymous one. Pair with `skip: true` so
|
|
235
|
+
the rule runs as a pure side effect:
|
|
236
|
+
|
|
237
|
+
```typescript
|
|
238
|
+
mapping: {
|
|
239
|
+
user: {
|
|
240
|
+
logout: {
|
|
241
|
+
skip: true,
|
|
242
|
+
settings: { reset: true },
|
|
243
|
+
},
|
|
244
|
+
},
|
|
245
|
+
}
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
## Consent
|
|
249
|
+
|
|
250
|
+
Declare the required consent keys on the destination via `config.consent`. A
|
|
251
|
+
`walker consent` event triggers the destination's `on('consent')` handler, which
|
|
252
|
+
checks every declared key against the event payload. If **all** required keys
|
|
253
|
+
are `true`, the destination calls `posthog.opt_in_capturing()`. Otherwise it
|
|
254
|
+
calls `posthog.opt_out_capturing()`, which stops capture, session replay, and
|
|
255
|
+
survey rendering.
|
|
256
|
+
|
|
257
|
+
```typescript
|
|
258
|
+
destinations: {
|
|
259
|
+
posthog: {
|
|
260
|
+
code: destinationPostHog,
|
|
261
|
+
config: {
|
|
262
|
+
consent: { analytics: true }, // required keys
|
|
263
|
+
settings: { apiKey: 'phc_...' },
|
|
264
|
+
},
|
|
265
|
+
},
|
|
266
|
+
}
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
Without `config.consent` the destination takes no action on consent changes; the
|
|
270
|
+
walkerOS `config.consent` gate still blocks unconsented events from reaching the
|
|
271
|
+
destination in the first place.
|
|
272
|
+
|
|
273
|
+
## Built-in Features (Config Passthrough)
|
|
274
|
+
|
|
275
|
+
All these PostHog features work via standard `posthog-js` init options — no
|
|
276
|
+
destination wiring required:
|
|
277
|
+
|
|
278
|
+
- **Session replay** —
|
|
279
|
+
`settings.session_recording: { maskAllInputs: true, ... }`
|
|
280
|
+
- **Feature flags** — `settings.bootstrap: { featureFlags: {...} }` for SSR,
|
|
281
|
+
`settings.advanced_disable_flags: true` to disable entirely. Access flags
|
|
282
|
+
directly via the `posthog` singleton.
|
|
283
|
+
- **Surveys** — automatic via the SDK; `settings.disable_surveys: true` opts out
|
|
284
|
+
- **Heatmaps** — `settings.capture_heatmaps: true`
|
|
285
|
+
- **Exception capture** — `settings.capture_exceptions: true`
|
|
286
|
+
- **Cookieless mode** — `settings.cookieless_mode: 'always' | 'on_reject'`
|
|
287
|
+
- **Person profiles** — `settings.person_profiles: 'identified_only'` (PostHog
|
|
288
|
+
default, privacy-friendly) or `'always'`
|
|
289
|
+
|
|
290
|
+
For programmatic access to flags, surveys, or exception reporting, import the
|
|
291
|
+
SDK singleton directly:
|
|
292
|
+
|
|
293
|
+
```typescript
|
|
294
|
+
import posthog from 'posthog-js';
|
|
295
|
+
posthog.getFeatureFlag('my-flag');
|
|
296
|
+
posthog.captureException(error);
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
## Contribute
|
|
300
|
+
|
|
301
|
+
Feel free to contribute by submitting an
|
|
302
|
+
[issue](https://github.com/elbwalker/walkerOS/issues), starting a
|
|
303
|
+
[discussion](https://github.com/elbwalker/walkerOS/discussions), or getting in
|
|
304
|
+
[contact](https://calendly.com/elb-alexander/30min).
|
|
305
|
+
|
|
306
|
+
## License
|
|
307
|
+
|
|
308
|
+
This project is licensed under the MIT License.
|
package/dist/dev.d.mts
ADDED
|
@@ -0,0 +1,269 @@
|
|
|
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 { PostHogConfig, Properties } from 'posthog-js';
|
|
6
|
+
|
|
7
|
+
declare const SettingsSchema: z.ZodObject<{
|
|
8
|
+
apiKey: z.ZodString;
|
|
9
|
+
api_host: z.ZodOptional<z.ZodString>;
|
|
10
|
+
ui_host: z.ZodOptional<z.ZodString>;
|
|
11
|
+
persistence: z.ZodOptional<z.ZodEnum<{
|
|
12
|
+
"localStorage+cookie": "localStorage+cookie";
|
|
13
|
+
cookie: "cookie";
|
|
14
|
+
localStorage: "localStorage";
|
|
15
|
+
sessionStorage: "sessionStorage";
|
|
16
|
+
memory: "memory";
|
|
17
|
+
}>>;
|
|
18
|
+
person_profiles: z.ZodOptional<z.ZodEnum<{
|
|
19
|
+
always: "always";
|
|
20
|
+
never: "never";
|
|
21
|
+
identified_only: "identified_only";
|
|
22
|
+
}>>;
|
|
23
|
+
autocapture: z.ZodOptional<z.ZodBoolean>;
|
|
24
|
+
capture_pageview: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"history_change">]>>;
|
|
25
|
+
capture_pageleave: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"if_capture_pageview">]>>;
|
|
26
|
+
capture_heatmaps: z.ZodOptional<z.ZodBoolean>;
|
|
27
|
+
capture_exceptions: z.ZodOptional<z.ZodBoolean>;
|
|
28
|
+
disable_surveys: z.ZodOptional<z.ZodBoolean>;
|
|
29
|
+
disable_session_recording: z.ZodOptional<z.ZodBoolean>;
|
|
30
|
+
advanced_disable_flags: z.ZodOptional<z.ZodBoolean>;
|
|
31
|
+
cookieless_mode: z.ZodOptional<z.ZodEnum<{
|
|
32
|
+
always: "always";
|
|
33
|
+
on_reject: "on_reject";
|
|
34
|
+
}>>;
|
|
35
|
+
debug: z.ZodOptional<z.ZodBoolean>;
|
|
36
|
+
session_recording: z.ZodOptional<z.ZodUnknown>;
|
|
37
|
+
bootstrap: z.ZodOptional<z.ZodUnknown>;
|
|
38
|
+
identify: z.ZodOptional<z.ZodUnknown>;
|
|
39
|
+
group: z.ZodOptional<z.ZodUnknown>;
|
|
40
|
+
}, z.core.$strip>;
|
|
41
|
+
type Settings$1 = z.infer<typeof SettingsSchema>;
|
|
42
|
+
|
|
43
|
+
declare const MappingSchema: z.ZodObject<{
|
|
44
|
+
identify: z.ZodOptional<z.ZodUnknown>;
|
|
45
|
+
group: z.ZodOptional<z.ZodUnknown>;
|
|
46
|
+
reset: z.ZodOptional<z.ZodUnknown>;
|
|
47
|
+
}, z.core.$strip>;
|
|
48
|
+
type Mapping = z.infer<typeof MappingSchema>;
|
|
49
|
+
|
|
50
|
+
declare const settings: _walkeros_core_dev.JSONSchema;
|
|
51
|
+
declare const mapping: _walkeros_core_dev.JSONSchema;
|
|
52
|
+
|
|
53
|
+
type index$1_Mapping = Mapping;
|
|
54
|
+
declare const index$1_MappingSchema: typeof MappingSchema;
|
|
55
|
+
declare const index$1_SettingsSchema: typeof SettingsSchema;
|
|
56
|
+
declare const index$1_mapping: typeof mapping;
|
|
57
|
+
declare const index$1_settings: typeof settings;
|
|
58
|
+
declare namespace index$1 {
|
|
59
|
+
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 };
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* Destination-level settings.
|
|
64
|
+
*
|
|
65
|
+
* PostHog's `PostHogConfig` interface has ~80 fields — extending the SDK type
|
|
66
|
+
* directly keeps IntelliSense complete and prevents drift. The destination adds:
|
|
67
|
+
* - `apiKey` (required) — first arg to `posthog.init(...)`, NOT an init option
|
|
68
|
+
* - `identify` — destination-level identity mapping
|
|
69
|
+
* - `include` — event sections flattened into `capture()` properties
|
|
70
|
+
* - `group` — destination-level group association
|
|
71
|
+
* - `_state` — runtime state (not user-facing, mutated by init/push)
|
|
72
|
+
*
|
|
73
|
+
* All other walkerOS-specific mapping features live under mapping.settings
|
|
74
|
+
* (see Mapping interface below). Built-in PostHog features (session_recording,
|
|
75
|
+
* advanced_disable_flags, disable_surveys, capture_heatmaps, capture_exceptions,
|
|
76
|
+
* bootstrap, cookieless_mode, ...) are passthrough via PostHogConfig.
|
|
77
|
+
*/
|
|
78
|
+
interface Settings extends Partial<PostHogConfig> {
|
|
79
|
+
/** PostHog project API key (e.g. "phc_XXX"). First arg to posthog.init(). */
|
|
80
|
+
apiKey: string;
|
|
81
|
+
/** Destination-level identity mapping, resolved on first push. */
|
|
82
|
+
identify?: Mapping$1.Value;
|
|
83
|
+
/** Destination-level group association, resolved on first push. */
|
|
84
|
+
group?: Mapping$1.Value;
|
|
85
|
+
/** Runtime state — populated by init() and mutated by push(). Not user-facing. */
|
|
86
|
+
_state?: RuntimeState;
|
|
87
|
+
}
|
|
88
|
+
interface RuntimeState {
|
|
89
|
+
/** Last-resolved identity values, used to skip redundant identify/group calls. */
|
|
90
|
+
lastIdentity?: {
|
|
91
|
+
distinctId?: string;
|
|
92
|
+
};
|
|
93
|
+
lastGroup?: {
|
|
94
|
+
type?: string;
|
|
95
|
+
key?: string;
|
|
96
|
+
};
|
|
97
|
+
}
|
|
98
|
+
/**
|
|
99
|
+
* PostHog SDK surface — the subset of `posthog-js` the destination actually
|
|
100
|
+
* uses. Mirrors the real module's default singleton export shape. Tests mock
|
|
101
|
+
* via env.posthog to intercept every call.
|
|
102
|
+
*/
|
|
103
|
+
interface PostHogSDK {
|
|
104
|
+
init: (token: string, config?: Partial<PostHogConfig> & {
|
|
105
|
+
loaded?: (posthog: PostHogSDK) => void;
|
|
106
|
+
}, name?: string) => PostHogSDK;
|
|
107
|
+
capture: (eventName: string, properties?: Properties) => void;
|
|
108
|
+
identify: (distinctId?: string, userPropertiesToSet?: Properties, userPropertiesToSetOnce?: Properties) => void;
|
|
109
|
+
setPersonProperties: (userPropertiesToSet?: Properties, userPropertiesToSetOnce?: Properties) => void;
|
|
110
|
+
group: (groupType: string, groupKey: string, groupPropertiesToSet?: Properties) => void;
|
|
111
|
+
reset: (resetDeviceId?: boolean) => void;
|
|
112
|
+
opt_in_capturing: (options?: {
|
|
113
|
+
captureEventName?: string | null | false;
|
|
114
|
+
captureProperties?: Properties;
|
|
115
|
+
}) => void;
|
|
116
|
+
opt_out_capturing: () => void;
|
|
117
|
+
}
|
|
118
|
+
/**
|
|
119
|
+
* Env — optional SDK override. Production leaves this undefined and the
|
|
120
|
+
* destination falls back to the real `posthog-js` default export. Tests
|
|
121
|
+
* provide a mock via env.posthog = { ... }.
|
|
122
|
+
*/
|
|
123
|
+
interface Env extends DestinationWeb.Env {
|
|
124
|
+
posthog?: PostHogSDK;
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/**
|
|
128
|
+
* Pre-init env — all methods are no-ops until the test runner wires spies.
|
|
129
|
+
*/
|
|
130
|
+
declare const init: Env | undefined;
|
|
131
|
+
/**
|
|
132
|
+
* Post-init env — same shape. The test runner clones this and replaces
|
|
133
|
+
* individual methods with jest.fn() so it can assert on calls.
|
|
134
|
+
*/
|
|
135
|
+
declare const push: Env;
|
|
136
|
+
/** Simulation tracking paths for CLI --simulate. */
|
|
137
|
+
declare const simulation: string[];
|
|
138
|
+
|
|
139
|
+
declare const env_init: typeof init;
|
|
140
|
+
declare const env_push: typeof push;
|
|
141
|
+
declare const env_simulation: typeof simulation;
|
|
142
|
+
declare namespace env {
|
|
143
|
+
export { env_init as init, env_push as push, env_simulation as simulation };
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
/**
|
|
147
|
+
* Examples may optionally carry destination-level settings.
|
|
148
|
+
* The test runner reads `settings` from the example and merges them
|
|
149
|
+
* into the base destination settings on top of the fixed apiKey.
|
|
150
|
+
*/
|
|
151
|
+
type PostHogStepExample = Flow.StepExample & {
|
|
152
|
+
settings?: Partial<Settings>;
|
|
153
|
+
configInclude?: string[];
|
|
154
|
+
};
|
|
155
|
+
/**
|
|
156
|
+
* Default event forwarding — every walkerOS event becomes
|
|
157
|
+
* posthog.capture(event.name, properties). With no mapping and no
|
|
158
|
+
* destination-level include, properties is `{}`.
|
|
159
|
+
*/
|
|
160
|
+
declare const defaultEventForwarding: PostHogStepExample;
|
|
161
|
+
/**
|
|
162
|
+
* Wildcard ignore — walkerOS's standard way to drop events. The rule
|
|
163
|
+
* matches but does nothing. The destination fires zero SDK calls.
|
|
164
|
+
*/
|
|
165
|
+
declare const wildcardIgnored: PostHogStepExample;
|
|
166
|
+
/**
|
|
167
|
+
* Destination-level settings.include flattens the walkerOS `data` section
|
|
168
|
+
* into prefixed capture() properties on every push.
|
|
169
|
+
*/
|
|
170
|
+
declare const destinationLevelInclude: PostHogStepExample;
|
|
171
|
+
/**
|
|
172
|
+
* Per-rule settings.include REPLACES destination-level include for the
|
|
173
|
+
* matched rule. Here destination-level sends `data`, but the rule
|
|
174
|
+
* overrides it with `globals` only.
|
|
175
|
+
*/
|
|
176
|
+
declare const ruleIncludeReplaces: PostHogStepExample;
|
|
177
|
+
/**
|
|
178
|
+
* Destination-level settings.identify fires on the first push (once the
|
|
179
|
+
* state cache is empty). The destination calls posthog.identify() and
|
|
180
|
+
* tracks the resolved distinctId in runtime state; subsequent pushes
|
|
181
|
+
* with unchanged values do NOT re-fire identify().
|
|
182
|
+
*
|
|
183
|
+
* With NO $set/$set_once keys in the resolved object, posthog.identify
|
|
184
|
+
* is called with just the distinctId.
|
|
185
|
+
*/
|
|
186
|
+
declare const destinationLevelIdentify: PostHogStepExample;
|
|
187
|
+
/**
|
|
188
|
+
* Per-event identify with the full PostHog identity vocabulary.
|
|
189
|
+
* This is the "user login" pattern: set a new distinctId and enrich
|
|
190
|
+
* person properties. `skip: true` suppresses the default posthog.capture()
|
|
191
|
+
* call because we're running identity side effects only.
|
|
192
|
+
*
|
|
193
|
+
* PostHog identify signature:
|
|
194
|
+
* posthog.identify(distinctId, $set, $set_once)
|
|
195
|
+
*/
|
|
196
|
+
declare const userLoginIdentify: PostHogStepExample;
|
|
197
|
+
/**
|
|
198
|
+
* Person-properties-only update — when the resolved identify object has
|
|
199
|
+
* NO `distinctId` key, the destination calls setPersonProperties($set, $set_once)
|
|
200
|
+
* instead of identify(). This is the "profile update" pattern: enrich
|
|
201
|
+
* user properties without changing identity.
|
|
202
|
+
*
|
|
203
|
+
* `skip` defaults to false here — we intentionally ALSO capture a
|
|
204
|
+
* "profile update" event so it shows up in PostHog's event stream.
|
|
205
|
+
*/
|
|
206
|
+
declare const profileUpdateSetPersonProperties: PostHogStepExample;
|
|
207
|
+
/**
|
|
208
|
+
* User logout — reset: true fires posthog.reset(), which clears the
|
|
209
|
+
* distinct ID and generates a new anonymous one. `skip: true` because
|
|
210
|
+
* we're only running the reset side effect, no default capture().
|
|
211
|
+
*/
|
|
212
|
+
declare const userLogoutReset: PostHogStepExample;
|
|
213
|
+
/**
|
|
214
|
+
* Group assignment + group properties. PostHog's group analytics (paid)
|
|
215
|
+
* aggregates events by company / team / project. The destination resolves
|
|
216
|
+
* `settings.group` to { type, key, properties? } and calls
|
|
217
|
+
* posthog.group(type, key, properties). `skip: true` keeps this a
|
|
218
|
+
* pure side-effect rule — no "company update" capture().
|
|
219
|
+
*/
|
|
220
|
+
declare const groupAssignmentWithProperties: PostHogStepExample;
|
|
221
|
+
/**
|
|
222
|
+
* Order complete — PostHog has no dedicated revenue API. Revenue tracking
|
|
223
|
+
* is just a capture() call with the revenue properties in data. This
|
|
224
|
+
* example pairs `include: ["data", "globals"]` with a destination-level
|
|
225
|
+
* capture. The order total, shipping, currency, etc. all become
|
|
226
|
+
* data_* properties on the PostHog event.
|
|
227
|
+
*/
|
|
228
|
+
declare const orderCompleteWithInclude: PostHogStepExample;
|
|
229
|
+
/**
|
|
230
|
+
* Consent revoked → posthog.opt_out_capturing(). The destination checks
|
|
231
|
+
* the consent key declared in config.consent (here "analytics") and
|
|
232
|
+
* toggles accordingly. opt_out_capturing() stops capture, session
|
|
233
|
+
* replay, AND survey rendering.
|
|
234
|
+
*
|
|
235
|
+
* Uses the canonical StepExample.command='consent' pattern: the test
|
|
236
|
+
* runner dispatches via elb('walker consent', in) instead of pushing
|
|
237
|
+
* an event.
|
|
238
|
+
*/
|
|
239
|
+
declare const consentRevokeOptOut: PostHogStepExample;
|
|
240
|
+
/**
|
|
241
|
+
* Consent granted → posthog.opt_in_capturing(). Called without arguments
|
|
242
|
+
* by default (the SDK fires its own $opt_in event).
|
|
243
|
+
*/
|
|
244
|
+
declare const consentGrantOptIn: PostHogStepExample;
|
|
245
|
+
|
|
246
|
+
type step_PostHogStepExample = PostHogStepExample;
|
|
247
|
+
declare const step_consentGrantOptIn: typeof consentGrantOptIn;
|
|
248
|
+
declare const step_consentRevokeOptOut: typeof consentRevokeOptOut;
|
|
249
|
+
declare const step_defaultEventForwarding: typeof defaultEventForwarding;
|
|
250
|
+
declare const step_destinationLevelIdentify: typeof destinationLevelIdentify;
|
|
251
|
+
declare const step_destinationLevelInclude: typeof destinationLevelInclude;
|
|
252
|
+
declare const step_groupAssignmentWithProperties: typeof groupAssignmentWithProperties;
|
|
253
|
+
declare const step_orderCompleteWithInclude: typeof orderCompleteWithInclude;
|
|
254
|
+
declare const step_profileUpdateSetPersonProperties: typeof profileUpdateSetPersonProperties;
|
|
255
|
+
declare const step_ruleIncludeReplaces: typeof ruleIncludeReplaces;
|
|
256
|
+
declare const step_userLoginIdentify: typeof userLoginIdentify;
|
|
257
|
+
declare const step_userLogoutReset: typeof userLogoutReset;
|
|
258
|
+
declare const step_wildcardIgnored: typeof wildcardIgnored;
|
|
259
|
+
declare namespace step {
|
|
260
|
+
export { type step_PostHogStepExample as PostHogStepExample, step_consentGrantOptIn as consentGrantOptIn, step_consentRevokeOptOut as consentRevokeOptOut, step_defaultEventForwarding as defaultEventForwarding, step_destinationLevelIdentify as destinationLevelIdentify, step_destinationLevelInclude as destinationLevelInclude, step_groupAssignmentWithProperties as groupAssignmentWithProperties, step_orderCompleteWithInclude as orderCompleteWithInclude, step_profileUpdateSetPersonProperties as profileUpdateSetPersonProperties, step_ruleIncludeReplaces as ruleIncludeReplaces, step_userLoginIdentify as userLoginIdentify, step_userLogoutReset as userLogoutReset, step_wildcardIgnored as wildcardIgnored };
|
|
261
|
+
}
|
|
262
|
+
|
|
263
|
+
declare const index_env: typeof env;
|
|
264
|
+
declare const index_step: typeof step;
|
|
265
|
+
declare namespace index {
|
|
266
|
+
export { index_env as env, index_step as step };
|
|
267
|
+
}
|
|
268
|
+
|
|
269
|
+
export { index as examples, index$1 as schemas };
|