@walkeros/web-destination-mixpanel 3.3.0-next-1776098542393

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 elbWalker GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,281 @@
+<p align="left">
+  <a href="https://www.walkeros.io">
+    <img alt="walkerOS" title="walkerOS" src="https://www.walkeros.io/img/walkerOS_logo.svg" width="256px"/>
+  </a>
+</p>
+
+# Mixpanel Destination for walkerOS
+
+[Source Code](https://github.com/elbwalker/walkerOS/tree/main/packages/web/destinations/mixpanel)
+&bull;
+[NPM Package](https://www.npmjs.com/package/@walkeros/web-destination-mixpanel)
+&bull; [Documentation](https://www.walkeros.io/docs/destinations/web/mixpanel)
+
+This package forwards walkerOS events to [Mixpanel](https://mixpanel.com/) —
+product analytics for tracking user behaviour, funnels, retention, and
+group-level metrics. Built on the official
+[`mixpanel-browser`](https://www.npmjs.com/package/mixpanel-browser) SDK.
+
+walkerOS follows a **source → collector → destination** architecture. This
+Mixpanel destination receives processed events from the walkerOS collector and
+forwards them as `track()` calls, identity updates, people-profile operations,
+group assignments, and consent changes.
+
+## Features
+
+- **Default event forwarding** — every walkerOS event becomes
+  `mixpanel.track(name, properties)` with no extra config
+- **Identity** — destination- or per-event `settings.identify` resolves to
+  `{ distinctId }` → `mixpanel.identify(distinctId)`, with runtime state diffing
+  so identical distinct IDs don't re-fire
+- **Full people vocabulary** — all eight Mixpanel operations supported: `set`,
+  `set_once`, `increment`, `append`, `union`, `remove`, `unset`, `delete_user`
+- **Groups** — user→group association via `mixpanel.set_group(key, id)` and
+  group-profile properties via `mixpanel.get_group(key, id).set/set_once/…`
+- **Reset on logout** — `settings.reset: true` calls `mixpanel.reset()` so the
+  next session starts with a fresh anonymous distinct ID
+- **Consent** — `on('consent')` handler derives required keys from
+  `config.consent` and toggles `opt_in_tracking` / `opt_out_tracking`
+- **Full SDK passthrough** — every `mixpanel-browser` `Config` option
+  (`api_host`, `persistence`, `batch_requests`, `record_sessions_percent`,
+  `cross_subdomain_cookie`, etc.) flows through directly
+
+## Installation
+
+```sh
+npm install @walkeros/web-destination-mixpanel
+```
+
+## Quick Start
+
+```typescript
+import { startFlow } from '@walkeros/collector';
+import { destinationMixpanel } from '@walkeros/web-destination-mixpanel';
+
+await startFlow({
+  destinations: {
+    mixpanel: {
+      code: destinationMixpanel,
+      config: {
+        consent: { analytics: true },
+        settings: {
+          apiKey: 'YOUR_PROJECT_TOKEN',
+          api_host: 'https://api-eu.mixpanel.com', // optional, for EU residency
+        },
+      },
+    },
+  },
+});
+```
+
+## Configuration
+
+### Settings (destination-level)
+
+| Name                      | Type                         | Description                                                                                      | Required |
+| ------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------ | -------- |
+| `apiKey`                  | `string`                     | Mixpanel project token (Project Settings → Access Keys)                                          | Yes      |
+| `api_host`                | `string`                     | Ingestion host. Default `https://api-js.mixpanel.com`. Use `https://api-eu.mixpanel.com` for EU. | No       |
+| `persistence`             | `'cookie' \| 'localStorage'` | Client-side persistence backend. Default `cookie`.                                               | No       |
+| `batch_requests`          | `boolean`                    | Use the `/batch` endpoint. Default `true`.                                                       | No       |
+| `record_sessions_percent` | `number`                     | Session replay sampling (0–100). Default `0`.                                                    | No       |
+| `track_pageview`          | `boolean \| string`          | Mixpanel auto-pageview. walkerOS default `false` (walkerOS sources handle page views).           | No       |
+| `autocapture`             | `boolean \| object`          | Mixpanel autocapture. walkerOS default `false`.                                                  | No       |
+| `include`                 | `string[]`                   | Event sections flattened into `track()` properties (`data`, `globals`, `context`, `user`, …)     | No       |
+| `identify`                | `Mapping.Value`              | Destination-level identity mapping; resolves to `{ distinctId }`                                 | No       |
+| `group`                   | `Mapping.Value`              | Destination-level group assignment; resolves to `{ key, id }`                                    | No       |
+
+All other `mixpanel-browser` `Config` options (snake_case) pass through directly
+— the destination's `Settings` type extends `Partial<Config>`.
+
+### Mapping (`rule.settings`)
+
+| Name           | Type                       | Description                                                                                                      |
+| -------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `identify`     | `Mapping.Value`            | Per-event identity override; resolves to `{ distinctId }`                                                        |
+| `include`      | `string[]`                 | Override destination-level `include` for this rule                                                               |
+| `people`       | `Mapping.Value`            | Per-event people operations (see People section below)                                                           |
+| `group`        | `Mapping.Value`            | Per-event group assignment; resolves to `{ key, id }`                                                            |
+| `groupProfile` | `Mapping.Value`            | Per-event group-profile operations; resolves to `{ key, id, set?, set_once?, union?, remove?, unset?, delete? }` |
+| `reset`        | `boolean \| Mapping.Value` | Logout trigger; resolves truthy → `mixpanel.reset()`                                                             |
+
+## Custom Event Properties
+
+Use `settings.include` (destination-level) or `rule.settings.include` (per-rule)
+to flatten walkerOS event sections into `track()` properties. Each section is
+prefixed (`data_*`, `globals_*`, `user_*`, …):
+
+```typescript
+// Destination-level: every event carries data_* properties
+settings: { include: ['data'] }
+
+// Per-rule override: this rule sends only globals_* properties
+mapping: {
+  order: {
+    complete: {
+      settings: { include: ['globals'] },
+    },
+  },
+}
+```
+
+For revenue events the Mixpanel `people.track_charge` API is deprecated
+(v2.78+); pass revenue fields as regular event properties instead — currency
+values in sample events use `"EUR"`.
+
+## Identity
+
+```typescript
+// Destination-level — every push with a user.id fires identify
+settings: {
+  apiKey: 'YOUR_TOKEN',
+  identify: { map: { distinctId: 'user.id' } },
+}
+
+// Per-event override
+mapping: {
+  user: {
+    login: {
+      settings: {
+        identify: { map: { distinctId: 'data.user_id' } },
+      },
+    },
+  },
+}
+```
+
+Runtime state diffing means identical `distinctId` values don't re-fire
+`mixpanel.identify()` — the SDK call only runs when the resolved value changes.
+
+## People
+
+All eight Mixpanel people operations are supported via `settings.people`. Each
+key in the resolved object fires a separate `mixpanel.people.*` call:
+
+| Key           | Signature                   | Fires                            |
+| ------------- | --------------------------- | -------------------------------- |
+| `set`         | `Record<string, unknown>`   | `mixpanel.people.set(obj)`       |
+| `set_once`    | `Record<string, unknown>`   | `mixpanel.people.set_once(obj)`  |
+| `increment`   | `Record<string, number>`    | `mixpanel.people.increment(obj)` |
+| `append`      | `Record<string, unknown>`   | `mixpanel.people.append(obj)`    |
+| `union`       | `Record<string, unknown[]>` | `mixpanel.people.union(obj)`     |
+| `remove`      | `Record<string, unknown>`   | `mixpanel.people.remove(obj)`    |
+| `unset`       | `string[]`                  | `mixpanel.people.unset(list)`    |
+| `delete_user` | `true`                      | `mixpanel.people.delete_user()`  |
+
+```typescript
+mapping: {
+  user: {
+    login: {
+      skip: true,
+      settings: {
+        identify: { map: { distinctId: 'data.user_id' } },
+        people: {
+          map: {
+            set: { map: { plan: 'data.plan', email: 'data.email' } },
+            set_once: { map: { first_login: 'timestamp' } },
+            increment: { map: { login_count: { value: 1 } } },
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+## Groups
+
+User→group association uses `mixpanel.set_group(key, id)`:
+
+```typescript
+mapping: {
+  user: {
+    login: {
+      settings: {
+        group: { map: { key: { value: 'company_id' }, id: 'data.company_id' } },
+      },
+    },
+  },
+}
+```
+
+Group profile properties use `mixpanel.get_group(key, id).set/…`:
+
+```typescript
+mapping: {
+  company: {
+    update: {
+      skip: true,
+      settings: {
+        groupProfile: {
+          map: {
+            key: { value: 'company_id' },
+            id: 'data.company_id',
+            set: {
+              map: { name: 'data.company_name', plan: 'data.plan' },
+            },
+            set_once: { map: { founded: 'data.founded_year' } },
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+## Reset / Logout
+
+```typescript
+mapping: {
+  user: {
+    logout: {
+      skip: true,
+      settings: { reset: true },
+    },
+  },
+}
+```
+
+`reset: true` fires `mixpanel.reset()`, clearing all persistence and generating
+a new anonymous distinct ID. The destination also clears its runtime identity
+state so the next identify call will fire again.
+
+## Consent
+
+Mixpanel consent is wired via the destination's `on('consent')` handler. Declare
+`config.consent` on the destination — the handler requires **all** declared keys
+to be granted to opt in:
+
+```typescript
+destinations: {
+  mixpanel: {
+    code: destinationMixpanel,
+    config: {
+      consent: { analytics: true },
+      settings: { apiKey: 'YOUR_TOKEN' },
+    },
+  },
+}
+```
+
+- All required keys granted → `mixpanel.opt_in_tracking()`
+- Any required key missing/denied → `mixpanel.opt_out_tracking()`
+- No `config.consent` declared → handler no-ops (relies on walkerOS's own
+  consent gate)
+
+## Destroy
+
+The `destroy()` hook calls `mixpanel.stop_batch_senders?.()` to halt the
+in-memory batcher. Mixpanel has no public flush API; already-queued events rely
+on the SDK's built-in `sendBeacon` unload handler.
+
+## Contribute
+
+Feel free to contribute by submitting an
+[issue](https://github.com/elbwalker/walkerOS/issues), starting a
+[discussion](https://github.com/elbwalker/walkerOS/discussions), or getting in
+[contact](https://calendly.com/elb-alexander/30min).
+
+## License
+
+This project is licensed under the MIT License.

package/dist/dev.d.mts

@@ -0,0 +1,253 @@
+import * as _walkeros_core_dev from '@walkeros/core/dev';
+import { z } from '@walkeros/core/dev';
+import { Mapping as Mapping$1, Flow } from '@walkeros/core';
+import { DestinationWeb } from '@walkeros/web-core';
+import { Config } from 'mixpanel-browser';
+
+declare const SettingsSchema: z.ZodObject<{
+    apiKey: z.ZodString;
+    api_host: z.ZodOptional<z.ZodString>;
+    persistence: z.ZodOptional<z.ZodEnum<{
+        cookie: "cookie";
+        localStorage: "localStorage";
+    }>>;
+    cross_subdomain_cookie: z.ZodOptional<z.ZodBoolean>;
+    cookie_expiration: z.ZodOptional<z.ZodNumber>;
+    secure_cookie: z.ZodOptional<z.ZodBoolean>;
+    ip: z.ZodOptional<z.ZodBoolean>;
+    batch_requests: z.ZodOptional<z.ZodBoolean>;
+    batch_size: z.ZodOptional<z.ZodNumber>;
+    batch_flush_interval_ms: z.ZodOptional<z.ZodNumber>;
+    debug: z.ZodOptional<z.ZodBoolean>;
+    opt_out_tracking_by_default: z.ZodOptional<z.ZodBoolean>;
+    track_pageview: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+    autocapture: z.ZodOptional<z.ZodUnknown>;
+    record_sessions_percent: z.ZodOptional<z.ZodNumber>;
+    record_mask_all_inputs: z.ZodOptional<z.ZodBoolean>;
+    identify: z.ZodOptional<z.ZodUnknown>;
+    group: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+type Settings$1 = z.infer<typeof SettingsSchema>;
+
+declare const MappingSchema: z.ZodObject<{
+    identify: z.ZodOptional<z.ZodUnknown>;
+    people: z.ZodOptional<z.ZodUnknown>;
+    group: z.ZodOptional<z.ZodUnknown>;
+    groupProfile: z.ZodOptional<z.ZodUnknown>;
+    reset: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+type Mapping = z.infer<typeof MappingSchema>;
+
+declare const settings: _walkeros_core_dev.JSONSchema;
+declare const mapping: _walkeros_core_dev.JSONSchema;
+
+type index$1_Mapping = Mapping;
+declare const index$1_MappingSchema: typeof MappingSchema;
+declare const index$1_SettingsSchema: typeof SettingsSchema;
+declare const index$1_mapping: typeof mapping;
+declare const index$1_settings: typeof settings;
+declare namespace index$1 {
+  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 };
+}
+
+/**
+ * Destination-level settings.
+ *
+ * Extends Mixpanel's `Config` so every `mixpanel.init()` option flows through
+ * without per-field plumbing. The destination adds walkerOS-specific keys:
+ *  - `apiKey` (required) — maps to the first arg of `mixpanel.init()`
+ *  - `identify` — destination-level identity mapping
+ *  - `include` — event sections flattened into `track()` properties
+ *  - `group` — destination-level group association
+ *  - `_state` — runtime state (not user-facing, mutated by init/push)
+ */
+interface Settings extends Partial<Config> {
+    apiKey: string;
+    identify?: Mapping$1.Value;
+    group?: Mapping$1.Value;
+    /** Runtime state — populated by init() and mutated by push(). Not user-facing. */
+    _state?: RuntimeState;
+}
+interface RuntimeState {
+    /** Last-set distinct_id, used to skip redundant identify() calls. */
+    lastIdentity?: {
+        distinctId?: string;
+    };
+}
+/**
+ * The `people` namespace on the mixpanel singleton. Mirrors the real SDK
+ * shape so tests can spy each method individually.
+ */
+interface MixpanelPeople {
+    set: (prop: string | Record<string, unknown>, to?: unknown, callback?: () => void) => void;
+    set_once: (prop: string | Record<string, unknown>, to?: unknown, callback?: () => void) => void;
+    increment: (prop: string | Record<string, number>, by?: number, callback?: () => void) => void;
+    append: (prop: string | Record<string, unknown>, value?: unknown, callback?: () => void) => void;
+    union: (prop: string | Record<string, unknown[]>, value?: unknown[], callback?: () => void) => void;
+    remove: (prop: string | Record<string, unknown>, value?: unknown, callback?: () => void) => void;
+    unset: (prop: string | string[], callback?: () => void) => void;
+    delete_user: () => void;
+}
+/**
+ * The handle returned by `mixpanel.get_group(key, id)`. Supports property
+ * operations on the group profile.
+ */
+interface MixpanelGroup {
+    set: (prop: string | Record<string, unknown>, to?: unknown, callback?: () => void) => void;
+    set_once: (prop: string | Record<string, unknown>, to?: unknown, callback?: () => void) => void;
+    unset: (prop: string | string[], callback?: () => void) => void;
+    union: (prop: string | Record<string, unknown[]>, value?: unknown[], callback?: () => void) => void;
+    remove: (prop: string | Record<string, unknown>, value?: unknown, callback?: () => void) => void;
+    delete: () => void;
+}
+/**
+ * Mixpanel SDK surface — the subset of `mixpanel-browser` the destination
+ * actually uses. Mirrors the singleton's shape so tests can mock the whole
+ * object via env.mixpanel.
+ */
+interface MixpanelSDK {
+    init: (token: string, config?: Partial<Config>, name?: string) => void;
+    track: (event: string, properties?: Record<string, unknown>, callback?: () => void) => void;
+    identify: (distinctId?: string) => void;
+    reset: () => void;
+    set_group: (groupKey: string, groupIds: string | string[], callback?: () => void) => void;
+    get_group: (groupKey: string, groupId: string) => MixpanelGroup;
+    opt_in_tracking: (options?: Record<string, unknown>) => void;
+    opt_out_tracking: (options?: Record<string, unknown>) => void;
+    stop_batch_senders?: () => void;
+    people: MixpanelPeople;
+}
+/**
+ * Env — optional SDK override. Production leaves this undefined and the
+ * destination falls back to the real `mixpanel-browser` default export.
+ * Tests provide a mock via env.mixpanel = { ... }.
+ */
+interface Env extends DestinationWeb.Env {
+    mixpanel?: MixpanelSDK;
+}
+
+/**
+ * Pre-init env — all methods are no-ops until the test runner wires spies.
+ */
+declare const init: Env | undefined;
+/**
+ * Post-init env — same shape. The test runner clones this and replaces
+ * individual methods with jest.fn() so it can assert on calls.
+ */
+declare const push: Env;
+/** Simulation tracking paths for CLI --simulate. */
+declare const simulation: string[];
+
+declare const env_init: typeof init;
+declare const env_push: typeof push;
+declare const env_simulation: typeof simulation;
+declare namespace env {
+  export { env_init as init, env_push as push, env_simulation as simulation };
+}
+
+/**
+ * Examples may optionally carry destination-level settings. The test runner
+ * reads `settings` from the example and merges it into the base destination
+ * settings on top of the fixed apiKey.
+ */
+type MixpanelStepExample = Flow.StepExample & {
+    settings?: Partial<Settings>;
+    configInclude?: string[];
+};
+/**
+ * Default event forwarding — every walkerOS event becomes
+ * mixpanel.track(event.name, properties). With no mapping and no
+ * destination-level include, properties is `{}`.
+ */
+declare const defaultEventForwarding: MixpanelStepExample;
+/**
+ * Wildcard ignore — walkerOS's standard way to drop events. The rule
+ * matches but does nothing. The destination fires zero SDK calls.
+ */
+declare const wildcardIgnored: MixpanelStepExample;
+/**
+ * Destination-level settings.include flattens the walkerOS `data` section
+ * into prefixed track() properties on every push.
+ */
+declare const destinationLevelInclude: MixpanelStepExample;
+/**
+ * Per-rule settings.include REPLACES destination-level include for the
+ * matched rule. Here destination-level sends `data`, but the rule
+ * overrides it with `globals` only.
+ */
+declare const ruleIncludeReplaces: MixpanelStepExample;
+/**
+ * Destination-level settings.identify fires on the first push. The
+ * destination resolves { distinctId } and calls mixpanel.identify(distinctId),
+ * then tracks the result in runtime state. Subsequent pushes with unchanged
+ * distinctId do NOT re-fire identify().
+ */
+declare const destinationLevelIdentify: MixpanelStepExample;
+/**
+ * Per-event identify + people operations — the canonical "user login"
+ * pattern. `skip: true` suppresses the default mixpanel.track() call
+ * because we're running identity side effects only.
+ */
+declare const userLoginIdentifyAndPeople: MixpanelStepExample;
+/**
+ * Full people operation vocabulary — a profile update rule that exercises
+ * set, set_once, increment, append, union, remove, and unset in a single
+ * rule. `skip: true` because only side effects are needed.
+ */
+declare const profileUpdateAllPeopleOperations: MixpanelStepExample;
+/**
+ * people.delete_user — destructive operation. The resolved people object
+ * uses `{ delete_user: true }` to trigger the call.
+ */
+declare const accountDeleteUser: MixpanelStepExample;
+/**
+ * User logout — reset: true fires mixpanel.reset(), which clears all
+ * persistence and generates a new anonymous distinct_id.
+ */
+declare const userLogoutReset: MixpanelStepExample;
+/**
+ * User-group association — settings.group resolves to { key, id } and
+ * calls mixpanel.set_group(key, id). Fires default track too.
+ */
+declare const userGroupAssociation: MixpanelStepExample;
+/**
+ * Group profile properties — settings.groupProfile resolves to
+ * { key, id, set?, set_once?, ... } and calls
+ * mixpanel.get_group(key, id).set(...), .set_once(...), etc.
+ */
+declare const companyUpdateGroupProfile: MixpanelStepExample;
+/**
+ * Consent revoked → mixpanel.opt_out_tracking(). The destination checks
+ * the consent keys declared in config.consent and toggles opt_out/opt_in.
+ */
+declare const consentRevokeOptOut: MixpanelStepExample;
+/**
+ * Consent granted → mixpanel.opt_in_tracking().
+ */
+declare const consentGrantOptIn: MixpanelStepExample;
+
+type step_MixpanelStepExample = MixpanelStepExample;
+declare const step_accountDeleteUser: typeof accountDeleteUser;
+declare const step_companyUpdateGroupProfile: typeof companyUpdateGroupProfile;
+declare const step_consentGrantOptIn: typeof consentGrantOptIn;
+declare const step_consentRevokeOptOut: typeof consentRevokeOptOut;
+declare const step_defaultEventForwarding: typeof defaultEventForwarding;
+declare const step_destinationLevelIdentify: typeof destinationLevelIdentify;
+declare const step_destinationLevelInclude: typeof destinationLevelInclude;
+declare const step_profileUpdateAllPeopleOperations: typeof profileUpdateAllPeopleOperations;
+declare const step_ruleIncludeReplaces: typeof ruleIncludeReplaces;
+declare const step_userGroupAssociation: typeof userGroupAssociation;
+declare const step_userLoginIdentifyAndPeople: typeof userLoginIdentifyAndPeople;
+declare const step_userLogoutReset: typeof userLogoutReset;
+declare const step_wildcardIgnored: typeof wildcardIgnored;
+declare namespace step {
+  export { type step_MixpanelStepExample as MixpanelStepExample, step_accountDeleteUser as accountDeleteUser, step_companyUpdateGroupProfile as companyUpdateGroupProfile, step_consentGrantOptIn as consentGrantOptIn, step_consentRevokeOptOut as consentRevokeOptOut, step_defaultEventForwarding as defaultEventForwarding, step_destinationLevelIdentify as destinationLevelIdentify, step_destinationLevelInclude as destinationLevelInclude, step_profileUpdateAllPeopleOperations as profileUpdateAllPeopleOperations, step_ruleIncludeReplaces as ruleIncludeReplaces, step_userGroupAssociation as userGroupAssociation, step_userLoginIdentifyAndPeople as userLoginIdentifyAndPeople, step_userLogoutReset as userLogoutReset, step_wildcardIgnored as wildcardIgnored };
+}
+
+declare const index_env: typeof env;
+declare const index_step: typeof step;
+declare namespace index {
+  export { index_env as env, index_step as step };
+}
+
+export { index as examples, index$1 as schemas };