@molecule/app-analytics-posthog 1.0.3 → 1.0.6
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/README.md +9 -2
- package/dist/provider.d.ts +2 -0
- package/dist/provider.d.ts.map +1 -1
- package/dist/provider.js +44 -1
- package/dist/provider.js.map +1 -1
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
|
|
|
3
3
|
Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
|
|
4
4
|
Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
|
|
5
5
|
To change this document, edit the module-level JSDoc in src/index.ts.
|
|
6
|
-
Generated: 2026-
|
|
6
|
+
Generated: 2026-11-08T06:24:37.313Z
|
|
7
7
|
-->
|
|
8
8
|
|
|
9
9
|
# @molecule/app-analytics-posthog
|
|
@@ -140,18 +140,21 @@ interface AnalyticsProvider {
|
|
|
140
140
|
* @param user - User properties including userId and optional traits.
|
|
141
141
|
*/
|
|
142
142
|
identify(user: AnalyticsUserProps): Promise<void>
|
|
143
|
+
|
|
143
144
|
/**
|
|
144
145
|
* Tracks a named event with optional properties.
|
|
145
146
|
*
|
|
146
147
|
* @param event - The event name and properties to track.
|
|
147
148
|
*/
|
|
148
149
|
track(event: AnalyticsEvent): Promise<void>
|
|
150
|
+
|
|
149
151
|
/**
|
|
150
152
|
* Records a page view.
|
|
151
153
|
*
|
|
152
154
|
* @param pageView - Page view details (name, path, properties).
|
|
153
155
|
*/
|
|
154
156
|
page(pageView: AnalyticsPageView): Promise<void>
|
|
157
|
+
|
|
155
158
|
/**
|
|
156
159
|
* Associates a user with a group (e.g. company, team).
|
|
157
160
|
*
|
|
@@ -159,10 +162,12 @@ interface AnalyticsProvider {
|
|
|
159
162
|
* @param traits - Arbitrary traits to associate with the group.
|
|
160
163
|
*/
|
|
161
164
|
group?(groupId: string, traits?: Record<string, unknown>): Promise<void>
|
|
165
|
+
|
|
162
166
|
/**
|
|
163
167
|
* Resets the current user identity and generates a new anonymous ID.
|
|
164
168
|
*/
|
|
165
169
|
reset?(): Promise<void>
|
|
170
|
+
|
|
166
171
|
/**
|
|
167
172
|
* Flushes any queued events to the analytics service immediately.
|
|
168
173
|
*/
|
|
@@ -194,6 +199,8 @@ a bonds.ts setup function) does NOT re-configure the SDK: `posthog-js`'s
|
|
|
194
199
|
is a no-op that keeps the FIRST configuration. This logs one actionable
|
|
195
200
|
warning naming the ignored call before the SDK's own generic warning fires.
|
|
196
201
|
|
|
202
|
+
SDK-added location/referrer properties are scrubbed by the installed `before_send` hook.
|
|
203
|
+
|
|
197
204
|
```typescript
|
|
198
205
|
function createProvider(options?: PostHogOptions): AnalyticsProvider
|
|
199
206
|
```
|
|
@@ -243,7 +250,7 @@ if (apiKey) {
|
|
|
243
250
|
|
|
244
251
|
Peer dependencies:
|
|
245
252
|
|
|
246
|
-
- `@molecule/app-analytics` ^1.
|
|
253
|
+
- `@molecule/app-analytics` ^1.1.1
|
|
247
254
|
|
|
248
255
|
### Environment Variables
|
|
249
256
|
|
package/dist/provider.d.ts
CHANGED
|
@@ -28,6 +28,8 @@ import type { PostHogOptions } from './types.js';
|
|
|
28
28
|
* is a no-op that keeps the FIRST configuration. This logs one actionable
|
|
29
29
|
* warning naming the ignored call before the SDK's own generic warning fires.
|
|
30
30
|
*
|
|
31
|
+
* SDK-added location/referrer properties are scrubbed by the installed `before_send` hook.
|
|
32
|
+
*
|
|
31
33
|
* @param options - PostHog configuration including `apiKey`, optional `host`, and `autocapture`.
|
|
32
34
|
* @returns An `AnalyticsProvider` backed by the PostHog browser SDK.
|
|
33
35
|
*/
|
package/dist/provider.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAGV,iBAAiB,EAElB,MAAM,yBAAyB,CAAA;
|
|
1
|
+
{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAGV,iBAAiB,EAElB,MAAM,yBAAyB,CAAA;AAGhC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAsChD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,cAAc,GAAI,UAAU,cAAc,KAAG,iBA+GzD,CAAA;AAID,6DAA6D;AAC7D,eAAO,MAAM,QAAQ,EAAE,iBAUrB,CAAA"}
|
package/dist/provider.js
CHANGED
|
@@ -6,6 +6,31 @@
|
|
|
6
6
|
* @module
|
|
7
7
|
*/
|
|
8
8
|
import { posthog } from 'posthog-js';
|
|
9
|
+
import { snapshotAnalyticsSdkUrls } from '@molecule/app-analytics';
|
|
10
|
+
/** Runs after posthog-js has added location, referrer, session and person properties. */
|
|
11
|
+
const scrubSdkUrls = (event) => snapshotAnalyticsSdkUrls(event);
|
|
12
|
+
const DETACHED_OBSERVERS = Symbol.for('@molecule/app-analytics-posthog/detached-observers');
|
|
13
|
+
/** The production ESM build minifies the emitter's field name, but not its public shape. */
|
|
14
|
+
const captureObserverEmitter = () => Object.values(Object.getOwnPropertyDescriptors(posthog))
|
|
15
|
+
.map((descriptor) => descriptor.value)
|
|
16
|
+
.find((value) => value !== null &&
|
|
17
|
+
typeof value === 'object' &&
|
|
18
|
+
typeof Reflect.get(value, 'emit') === 'function' &&
|
|
19
|
+
typeof Reflect.get(value, 'on') === 'function');
|
|
20
|
+
/** eventCaptured is an observer API: mutations must not reach the already-captured request. */
|
|
21
|
+
const detachCaptureObservers = () => {
|
|
22
|
+
const emitter = captureObserverEmitter();
|
|
23
|
+
if (!emitter || emitter[DETACHED_OBSERVERS])
|
|
24
|
+
return;
|
|
25
|
+
const emit = emitter.emit;
|
|
26
|
+
Object.defineProperty(emitter, DETACHED_OBSERVERS, { value: true });
|
|
27
|
+
emitter.emit = function (event, ...args) {
|
|
28
|
+
const captured = event === 'eventCaptured' && args.length > 0
|
|
29
|
+
? [snapshotAnalyticsSdkUrls(args[0]), ...args.slice(1)]
|
|
30
|
+
: args;
|
|
31
|
+
return Reflect.apply(emit, this, [event, ...captured]);
|
|
32
|
+
};
|
|
33
|
+
};
|
|
9
34
|
/**
|
|
10
35
|
* Creates a PostHog analytics provider using `posthog-js`. Initializes the SDK with the
|
|
11
36
|
* provided API key and host, and returns an `AnalyticsProvider` that maps molecule events to
|
|
@@ -27,6 +52,8 @@ import { posthog } from 'posthog-js';
|
|
|
27
52
|
* is a no-op that keeps the FIRST configuration. This logs one actionable
|
|
28
53
|
* warning naming the ignored call before the SDK's own generic warning fires.
|
|
29
54
|
*
|
|
55
|
+
* SDK-added location/referrer properties are scrubbed by the installed `before_send` hook.
|
|
56
|
+
*
|
|
30
57
|
* @param options - PostHog configuration including `apiKey`, optional `host`, and `autocapture`.
|
|
31
58
|
* @returns An `AnalyticsProvider` backed by the PostHog browser SDK.
|
|
32
59
|
*/
|
|
@@ -75,7 +102,22 @@ export const createProvider = (options) => {
|
|
|
75
102
|
...(options?.host ? { api_host: options.host } : {}),
|
|
76
103
|
autocapture: options?.autocapture ?? false,
|
|
77
104
|
capture_pageview: false, // We handle page views manually via auto-tracking
|
|
105
|
+
before_send: scrubSdkUrls,
|
|
78
106
|
});
|
|
107
|
+
// A pre-initialized singleton keeps its first config. Compose in that case and put this hook
|
|
108
|
+
// LAST so another hook cannot re-add a location/referrer credential after the scrub.
|
|
109
|
+
const configuredBeforeSend = posthog.config?.before_send;
|
|
110
|
+
if (configuredBeforeSend !== scrubSdkUrls && typeof posthog.set_config === 'function') {
|
|
111
|
+
const previous = Array.isArray(configuredBeforeSend)
|
|
112
|
+
? configuredBeforeSend
|
|
113
|
+
: configuredBeforeSend
|
|
114
|
+
? [configuredBeforeSend]
|
|
115
|
+
: [];
|
|
116
|
+
posthog.set_config({
|
|
117
|
+
before_send: [...previous.filter((hook) => hook !== scrubSdkUrls), scrubSdkUrls],
|
|
118
|
+
});
|
|
119
|
+
}
|
|
120
|
+
detachCaptureObservers();
|
|
79
121
|
return {
|
|
80
122
|
async identify(user) {
|
|
81
123
|
posthog.identify(user.userId, {
|
|
@@ -88,7 +130,8 @@ export const createProvider = (options) => {
|
|
|
88
130
|
// posthog-js supports a client-set timestamp via CaptureOptions — honor
|
|
89
131
|
// the interface's `timestamp` field instead of silently dropping it.
|
|
90
132
|
if (event.timestamp) {
|
|
91
|
-
|
|
133
|
+
const timestamp = event.timestamp instanceof Date ? event.timestamp : new Date(String(event.timestamp));
|
|
134
|
+
posthog.capture(event.name, event.properties, { timestamp });
|
|
92
135
|
}
|
|
93
136
|
else {
|
|
94
137
|
posthog.capture(event.name, event.properties);
|
package/dist/provider.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;
|
|
1
|
+
{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@molecule/app-analytics-posthog",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.6",
|
|
4
4
|
"description": "PostHog analytics provider for molecule.dev frontend",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -30,10 +30,10 @@
|
|
|
30
30
|
"posthog-js": "1.438.21"
|
|
31
31
|
},
|
|
32
32
|
"peerDependencies": {
|
|
33
|
-
"@molecule/app-analytics": "^1.
|
|
33
|
+
"@molecule/app-analytics": "^1.1.1"
|
|
34
34
|
},
|
|
35
35
|
"devDependencies": {
|
|
36
|
-
"@molecule/app-analytics": "1.
|
|
36
|
+
"@molecule/app-analytics": "1.1.3",
|
|
37
37
|
"@types/node": "26.6.5",
|
|
38
38
|
"typescript": "6.0.3",
|
|
39
39
|
"vitest": "4.1.12"
|