@walkeros/web-destination-posthog 4.1.0-next-1778668930820 → 4.1.0

package/CHANGELOG.md

@@ -0,0 +1,122 @@
+# @walkeros/web-destination-posthog
+
+## 4.1.0
+
+### Patch Changes
+
+- Updated dependencies [e155ff8]
+- Updated dependencies [e800974]
+- Updated dependencies [e155ff8]
+- Updated dependencies [1a8f2d7]
+- Updated dependencies [1a8f2d7]
+- Updated dependencies [b276173]
+- Updated dependencies [dd9f5ad]
+- Updated dependencies [c60ef35]
+- Updated dependencies [adeebea]
+- Updated dependencies [13aaeaa]
+- Updated dependencies [e800974]
+- Updated dependencies [adeebea]
+- Updated dependencies [e800974]
+- Updated dependencies [e800974]
+- Updated dependencies [058f7ed]
+- Updated dependencies [28a8ac2]
+- Updated dependencies [fd6076e]
+  - @walkeros/core@4.1.0
+  - @walkeros/web-core@4.1.0
+
+## 4.0.2
+
+### Patch Changes
+
+- @walkeros/web-core@4.0.2
+
+## 4.0.1
+
+### Patch Changes
+
+- @walkeros/web-core@4.0.1
+
+## 4.0.0
+
+### Patch Changes
+
+- Updated dependencies [93ea9c4]
+  - @walkeros/web-core@4.0.0
+
+## 3.4.2
+
+### Patch Changes
+
+- @walkeros/web-core@3.4.2
+
+## 3.4.1
+
+### Patch Changes
+
+- Updated dependencies [caea905]
+  - @walkeros/web-core@3.4.1
+
+## 3.4.0
+
+### Minor Changes
+
+- 724f97e: Migrate every step example in every walkerOS package to the
+  standardized `[callable, ...args][]` shape introduced in `@walkeros/core`.
+  Every step example's `out` is now an array of effect tuples whose first
+  element is the callable's public SDK name (`'gtag'`, `'analytics.track'`,
+  `'fbq'`, `'dataLayer.push'`, `'sendServer'`, `'fetch'`, `'trackClient.track'`,
+  `'amplitude.track'`, `'fs.writeFile'`, `'producer.send'`, `'client.xadd'`,
+  `'client.send'`, `'dataset.table.insert'`, etc.). Source examples use `'elb'`
+  as the callable; transformer examples use the reserved `'return'` keyword;
+  store examples use store-operation callables (`'get'`, `'set'`). Tests capture
+  real calls on each component's spy and assert against `example.out` directly —
+  the hardcoded `PACKAGE_CALLS` registry in the app is no longer consulted
+  (emptied; plan #3 removes it structurally).
+
+### Patch Changes
+
+- @walkeros/web-core@3.4.0
+
+## 3.3.1
+
+### Patch Changes
+
+- @walkeros/web-core@3.3.1
+
+## 3.3.0
+
+### Minor Changes
+
+- 08c365a: Add PostHog web destination (`@walkeros/web-destination-posthog`) —
+  product analytics, identity with `$set`/`$set_once` person properties, groups,
+  logout via reset, consent opt-in/opt-out, plus passthrough for all built-in
+  PostHog features (session replay, feature flags, surveys, heatmaps, error
+  tracking) via the official `posthog-js` npm package.
+  - Default event forwarding: every walkerOS event becomes
+    `posthog.capture(name, properties)`
+  - Custom event properties: `settings.include` flattens walkerOS event sections
+    with prefix (`data_*`, `globals_*`, etc.)
+  - Identity: destination-level + per-event `settings.identify`, resolving to
+    `{ distinctId?, $set?, $set_once? }`. With `distinctId`:
+    `posthog.identify()`. Without `distinctId`: `posthog.setPersonProperties()`
+    (property-only updates). Runtime state diffing skips redundant `identify()`
+    calls when `distinctId` hasn't changed.
+  - Groups: `settings.group` for B2B workflows — destination-level or per-event,
+    tracked in runtime state
+  - Reset: `settings.reset: true` calls `posthog.reset()` on logout
+  - Consent: `on('consent')` handler derives the consent key from
+    `config.consent` and toggles
+    `posthog.opt_in_capturing()`/`opt_out_capturing()`
+  - Built-in features (config passthrough, no destination code): session
+    recording, feature flags, surveys, heatmaps, exceptions, cookieless mode,
+    bootstrap
+  - walkerOS defaults override PostHog defaults: `autocapture: false`,
+    `capture_pageview: false`, `capture_pageleave: false` — walkerOS sources
+    handle event capture
+  - SDK resolution follows the `env?.posthog ?? posthog` pattern (mirrors
+    `@walkeros/web-destination-clarity` and `@walkeros/server-destination-gcp`
+    BigQuery)
+
+### Patch Changes
+
+- @walkeros/web-core@3.3.0

package/README.md

@@ -4,298 +4,46 @@
   </a>
 </p>
 
-# PostHog Destination for walkerOS
+# @walkeros/web-destination-posthog
 
-[Source Code](https://github.com/elbwalker/walkerOS/tree/main/packages/web/destinations/posthog)
-&bull;
-[NPM Package](https://www.npmjs.com/package/@walkeros/web-destination-posthog)
-&bull; [Documentation](https://www.walkeros.io/docs/destinations/web/posthog)
-
-This package forwards walkerOS events to [PostHog](https://posthog.com/) -
-product analytics, session replay, feature flags, surveys, and heatmaps. Built
-on the official [`posthog-js`](https://www.npmjs.com/package/posthog-js) SDK.
+Product analytics, session replay, feature flags, and surveys.
 
-walkerOS follows a **source → collector → destination** architecture. This
-PostHog destination receives processed events from the walkerOS collector and
-forwards them as PostHog captures, identifies, group assignments, and consent
-updates. All built-in PostHog features (session replay, feature flags, surveys,
-heatmaps, exception capture) are available through SDK init passthrough - no
-destination-specific plugins required.
-
-## Features
-
-- **Default event forwarding** - every walkerOS event becomes
-  `posthog.capture(event.name, properties)` with no additional config
-- **Custom event properties** - flatten walkerOS event sections via
-  `settings.include` (prefixed as `data_*`, `globals_*`, etc.)
-- **Identity** - destination-level and per-event identity mapping resolving to
-  `{ distinctId?, $set?, $set_once? }`. With `distinctId`: `posthog.identify()`.
-  Without `distinctId`: `posthog.setPersonProperties()` for pure person-property
-  updates. Runtime state diffing skips redundant identify calls when the
-  resolved values have not changed.
-- **Groups** - B2B-style group analytics via `settings.group`; resolves to
-  `{ type, key, properties? }` and calls `posthog.group(...)`
-- **Logout** - `reset: true` triggers `posthog.reset()` to clear the distinct ID
-  and regenerate an anonymous one
-- **Consent** - declares required consent keys via `config.consent`; a
-  `walker consent` event with all required keys granted calls
-  `posthog.opt_in_capturing()`, otherwise `posthog.opt_out_capturing()`
-- **Built-in PostHog features as config passthrough** - session replay
-  (`session_recording`), feature flags (`bootstrap`, `advanced_disable_flags`),
-  surveys (`disable_surveys`), heatmaps (`capture_heatmaps`), exception capture
-  (`capture_exceptions`), cookieless mode (`cookieless_mode`). All
-  `PostHogConfig` fields pass through unchanged.
+[Documentation](https://www.walkeros.io/docs/destinations/web/posthog) &bull;
+[NPM Package](https://www.npmjs.com/package/@walkeros/web-destination-posthog)
+&bull;
+[Source Code](https://github.com/elbwalker/walkerOS/tree/main/packages/web/destinations/posthog)
 
 ## Installation
 
-```sh
+```bash
 npm install @walkeros/web-destination-posthog
 ```
 
-## Quick Start
-
-```typescript
-import { startFlow } from '@walkeros/collector';
-import { destinationPostHog } from '@walkeros/web-destination-posthog';
+## Quick start
 
-await startFlow({
-  destinations: {
-    posthog: {
-      code: destinationPostHog,
-      config: {
-        settings: {
-          apiKey: 'phc_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
-          api_host: 'https://eu.i.posthog.com', // or us.i.posthog.com
-        },
+```json
+{
+  "version": 4,
+  "flows": {
+    "default": {
+      "config": {
+        "platform": "web"
       },
-    },
-  },
-});
-```
-
-## Configuration
-
-### Settings (destination-level)
-
-| Name       | Type            | Description                                                                                        | Required |
-| ---------- | --------------- | -------------------------------------------------------------------------------------------------- | -------- |
-| `apiKey`   | `string`        | PostHog project API key (starts with `phc_`)                                                       | Yes      |
-| `api_host` | `string`        | PostHog ingestion host. Default `https://us.i.posthog.com`. Use `https://eu.i.posthog.com` for EU. | No       |
-| `include`  | `string[]`      | walkerOS event sections to flatten into `capture()` properties (`data`, `globals`, `context`, …)   | No       |
-| `identify` | `Mapping.Value` | Destination-level identity mapping; resolves to `{ distinctId?, $set?, $set_once? }`               | No       |
-| `group`    | `Mapping.Value` | Destination-level group assignment; resolves to `{ type, key, properties? }`                       | No       |
-
-All other [`PostHogConfig`](https://posthog.com/docs/libraries/js#config) fields
-(e.g. `session_recording`, `capture_heatmaps`, `bootstrap`, `cookieless_mode`)
-pass through unchanged. walkerOS sets three defaults that differ from PostHog's
-built-ins: `autocapture: false`, `capture_pageview: false`,
-`capture_pageleave: false` - because walkerOS sources handle event capture.
-Override them explicitly in `settings` if you want PostHog's autocapture on.
-
-### Mapping (`rule.settings`)
-
-| Name       | Type                       | Description                                                                             |
-| ---------- | -------------------------- | --------------------------------------------------------------------------------------- |
-| `identify` | `Mapping.Value`            | Per-event identity. Resolves to `{ distinctId?, $set?, $set_once? }`                    |
-| `include`  | `string[]`                 | Override destination-level `include` for this rule                                      |
-| `group`    | `Mapping.Value`            | Per-event group assignment. Resolves to `{ type, key, properties? }`                    |
-| `reset`    | `Mapping.Value \| boolean` | Logout trigger. Truthy value → `posthog.reset()`. Typically paired with `silent: true`. |
-
-## Custom Event Properties
-
-Two ways to attach properties to a PostHog capture:
-
-```typescript
-// 1. Flatten walkerOS sections with settings.include
-config: {
-  settings: {
-    apiKey: 'phc_...',
-    include: ['data', 'globals'], // → data_*, globals_* on every event
-  },
-}
-
-// 2. Override per-rule via mapping.settings.include
-mapping: {
-  order: {
-    complete: {
-      settings: {
-        include: ['data', 'globals'], // EUR currency, totals, pagegroup
-      },
-    },
-  },
+      "destinations": {
+        "posthog": {
+          "package": "@walkeros/web-destination-posthog",
+          "config": {}
+        }
+      }
+    }
+  }
 }
 ```
 
-PostHog has no dedicated revenue API - revenue events are regular `capture()`
-calls with the revenue properties in the payload. Use `include: ['data']` on an
-`order complete` rule to forward `data_total`, `data_currency` (e.g. `"EUR"`),
-`data_shipping`, etc.
-
-## Identity
+## Documentation
 
-Destination-level identify fires on the first push and re-fires only when the
-resolved `distinctId` changes (runtime state diffing, skip redundant calls):
-
-```typescript
-settings: {
-  apiKey: 'phc_...',
-  identify: {
-    map: {
-      distinctId: 'user.id',
-    },
-  },
-}
-```
-
-Per-event identify supports the full PostHog vocabulary - `distinctId`, `$set`
-(person properties), `$set_once` (set-if-unset person properties). The
-destination calls `posthog.identify(distinctId, $set, $set_once)`:
-
-```typescript
-mapping: {
-  user: {
-    login: {
-      silent: true, // side-effect only, no capture() for user login
-      settings: {
-        identify: {
-          map: {
-            distinctId: 'data.user_id',
-            $set: {
-              map: {
-                email: 'data.email',
-                plan: 'data.plan',
-              },
-            },
-            $set_once: {
-              map: { first_login: 'timestamp' },
-            },
-          },
-        },
-      },
-    },
-  },
-}
-```
-
-**Person properties without identity change.** When the resolved identify object
-has no `distinctId`, the destination calls
-`posthog.setPersonProperties($set, $set_once)` instead - useful for profile
-updates that should not create a new identity:
-
-```typescript
-mapping: {
-  profile: {
-    update: {
-      settings: {
-        identify: {
-          map: {
-            $set: { map: { name: 'data.name' } },
-          },
-        },
-      },
-    },
-  },
-}
-```
-
-## Groups
-
-PostHog's group analytics (Scale/Enterprise) aggregates events by company, team,
-or any custom group type. Configure a group mapping at destination or rule level
-
-- the destination calls `posthog.group(type, key, properties?)`:
-
-```typescript
-mapping: {
-  company: {
-    update: {
-      silent: true,
-      settings: {
-        group: {
-          map: {
-            type: { value: 'company' },
-            key: 'data.company_id',
-            properties: {
-              map: {
-                name: 'data.company_name',
-                plan: 'data.plan',
-              },
-            },
-          },
-        },
-      },
-    },
-  },
-}
-```
-
-## Logout
-
-`reset: true` (or any truthy mapping value) calls `posthog.reset()`, clearing
-the distinct ID and generating a new anonymous one. Pair with `silent: true` so
-the rule runs as a pure side effect:
-
-```typescript
-mapping: {
-  user: {
-    logout: {
-      silent: true,
-      settings: { reset: true },
-    },
-  },
-}
-```
-
-## Consent
-
-Declare the required consent keys on the destination via `config.consent`. A
-`walker consent` event triggers the destination's `on('consent')` handler, which
-checks every declared key against the event payload. If **all** required keys
-are `true`, the destination calls `posthog.opt_in_capturing()`. Otherwise it
-calls `posthog.opt_out_capturing()`, which stops capture, session replay, and
-survey rendering.
-
-```typescript
-destinations: {
-  posthog: {
-    code: destinationPostHog,
-    config: {
-      consent: { analytics: true }, // required keys
-      settings: { apiKey: 'phc_...' },
-    },
-  },
-}
-```
-
-Without `config.consent` the destination takes no action on consent changes; the
-walkerOS `config.consent` gate still blocks unconsented events from reaching the
-destination in the first place.
-
-## Built-in Features (Config Passthrough)
-
-All these PostHog features work via standard `posthog-js` init options - no
-destination wiring required:
-
-- **Session replay** -
-  `settings.session_recording: { maskAllInputs: true, ... }`
-- **Feature flags** - `settings.bootstrap: { featureFlags: {...} }` for SSR,
-  `settings.advanced_disable_flags: true` to disable entirely. Access flags
-  directly via the `posthog` singleton.
-- **Surveys** - automatic via the SDK; `settings.disable_surveys: true` opts out
-- **Heatmaps** - `settings.capture_heatmaps: true`
-- **Exception capture** - `settings.capture_exceptions: true`
-- **Cookieless mode** - `settings.cookieless_mode: 'always' | 'on_reject'`
-- **Person profiles** - `settings.person_profiles: 'identified_only'` (PostHog
-  default, privacy-friendly) or `'always'`
-
-For programmatic access to flags, surveys, or exception reporting, import the
-SDK singleton directly:
-
-```typescript
-import posthog from 'posthog-js';
-posthog.getFeatureFlag('my-flag');
-posthog.captureException(error);
-```
+Full configuration, mapping, and examples live in the docs:
+**https://www.walkeros.io/docs/destinations/web/posthog**
 
 ## Contribute
 
@@ -306,4 +54,4 @@ Feel free to contribute by submitting an
 
 ## License
 
-This project is licensed under the MIT License.
+MIT