@walkeros/web-destination-heap 3.4.0-next-1776749829492

package/README.md

@@ -0,0 +1,151 @@
+<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>
+
+# Heap Destination for walkerOS
+
+[Source Code](https://github.com/elbwalker/walkerOS/tree/main/packages/web/destinations/heap)
+&bull;
+[NPM Package](https://www.npmjs.com/package/@walkeros/web-destination-heap)
+&bull; [Documentation](https://www.walkeros.io/docs/destinations/web/heap)
+
+This package forwards walkerOS events to [Heap](https://www.heap.io/) — product
+analytics with auto-capture, heatmaps, and session replay. Loads the official
+Heap snippet from Heap's CDN and forwards events through `window.heap.track()`.
+
+walkerOS follows a **source → collector → destination** architecture. This Heap
+destination receives processed events from the walkerOS collector and forwards
+them as `heap.track()` calls plus identity and persistent property updates.
+
+## Features
+
+- **Default event forwarding** — every walkerOS event becomes
+  `heap.track(name, properties)`
+- **Identity** — `heap.identify(id)` and `heap.resetIdentity()` for login/logout
+- **User properties** — `heap.addUserProperties({...})` at destination or rule
+  level
+- **Persistent event properties** — `heap.addEventProperties({...})` and
+  `heap.clearEventProperties()` via rule settings
+- **Consent** — `heap.startTracking()` / `heap.stopTracking()` wired to walkerOS
+  `config.consent`
+- **Snippet injection** — loads `heap-<appId>.js` from Heap's CDN with
+  `disablePageviewAutocapture: true` and `disableTextCapture: true` defaults so
+  walkerOS sources own event capture
+
+## Installation
+
+```sh
+npm install @walkeros/web-destination-heap
+```
+
+## Quick Start
+
+```typescript
+import { startFlow } from '@walkeros/collector';
+import { destinationHeap } from '@walkeros/web-destination-heap';
+
+await startFlow({
+  destinations: {
+    heap: {
+      code: destinationHeap,
+      config: {
+        loadScript: true,
+        settings: {
+          appId: 'YOUR_HEAP_APP_ID',
+        },
+      },
+    },
+  },
+});
+```
+
+## Configuration
+
+### Settings (destination-level)
+
+| Name                         | Type            | Description                                                                                      | Required |
+| ---------------------------- | --------------- | ------------------------------------------------------------------------------------------------ | -------- |
+| `appId`                      | `string`        | Heap App ID (Project > Settings > App ID)                                                        | Yes      |
+| `disableTextCapture`         | `boolean`       | Disable Heap auto text capture. Defaults to `true`.                                              | No       |
+| `disablePageviewAutocapture` | `boolean`       | Disable Heap automatic pageview tracking. Defaults to `true` (walkerOS sources emit pageviews).  | No       |
+| `disableSessionReplay`       | `boolean`       | Disable Heap session replay.                                                                     | No       |
+| `secureCookie`               | `boolean`       | SSL-only cookies.                                                                                | No       |
+| `ingestServer`               | `string`        | Custom server endpoint (first-party proxy).                                                      | No       |
+| `identify`                   | `Mapping.Value` | Destination-level identity mapping — resolves to a string for `heap.identify()`                  | No       |
+| `userProperties`             | `Mapping.Value` | Destination-level user properties mapping — resolves to an object for `heap.addUserProperties()` | No       |
+| `heapConfig`                 | `HeapConfig`    | Passthrough for additional `heap.load()` options                                                 | No       |
+
+### Mapping (`rule.settings`)
+
+| Name                   | Type                       | Description                                                                      |
+| ---------------------- | -------------------------- | -------------------------------------------------------------------------------- |
+| `identify`             | `Mapping.Value`            | Per-event identity — resolves to a string for `heap.identify()`                  |
+| `reset`                | `boolean \| Mapping.Value` | Truthy triggers `heap.resetIdentity()` (e.g. on logout)                          |
+| `userProperties`       | `Mapping.Value`            | Per-event user properties — resolves to object for `heap.addUserProperties()`    |
+| `eventProperties`      | `Mapping.Value`            | Persistent event properties — resolves to object for `heap.addEventProperties()` |
+| `clearEventProperties` | `boolean \| Mapping.Value` | Truthy triggers `heap.clearEventProperties()`                                    |
+
+Standard mapping features also apply:
+
+- `name` — rename the forwarded event (`heap.track(<new name>, ...)`)
+- `skip` — suppress the default `heap.track(...)` call while still running
+  `identify` / `userProperties` / `reset` / `eventProperties`
+- `ignore` — drop the event entirely
+- `data` — resolve event properties forwarded as the second argument to
+  `heap.track(...)`
+
+## Identity
+
+Heap identity is sticky — call `heap.identify(id)` on login and
+`heap.resetIdentity()` on logout. A typical mapping:
+
+```typescript
+mapping: {
+  user: {
+    login: {
+      skip: true,
+      settings: {
+        identify: 'data.email',
+        userProperties: {
+          map: { plan: 'data.plan', company: 'data.company' },
+        },
+      },
+    },
+    logout: {
+      skip: true,
+      settings: { reset: true },
+    },
+  },
+}
+```
+
+## Consent
+
+The destination wires walkerOS `config.consent` to Heap's runtime consent API.
+When all required consent keys are `true`, `heap.startTracking()` is called;
+otherwise `heap.stopTracking()`.
+
+```typescript
+destinations: {
+  heap: {
+    code: destinationHeap,
+    config: {
+      consent: { analytics: true },
+      settings: { appId: 'YOUR_HEAP_APP_ID' },
+    },
+  },
+}
+```
+
+## 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,207 @@
+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';
+
+declare const SettingsSchema: z.ZodObject<{
+    appId: z.ZodString;
+    disableTextCapture: z.ZodOptional<z.ZodBoolean>;
+    disablePageviewAutocapture: z.ZodOptional<z.ZodBoolean>;
+    disableSessionReplay: z.ZodOptional<z.ZodBoolean>;
+    secureCookie: z.ZodOptional<z.ZodBoolean>;
+    ingestServer: z.ZodOptional<z.ZodString>;
+    identify: z.ZodOptional<z.ZodUnknown>;
+    userProperties: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+type Settings$1 = z.infer<typeof SettingsSchema>;
+
+declare const MappingSchema: z.ZodObject<{
+    identify: z.ZodOptional<z.ZodUnknown>;
+    reset: z.ZodOptional<z.ZodUnknown>;
+    userProperties: z.ZodOptional<z.ZodUnknown>;
+    eventProperties: z.ZodOptional<z.ZodUnknown>;
+    clearEventProperties: 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 };
+}
+
+/** Property value types accepted by Heap SDK methods. */
+type HeapPropertyValue = string | number | boolean;
+/** Options accepted by heap.load() as the second argument. */
+interface HeapConfig {
+    disableTextCapture?: boolean;
+    disablePageviewAutocapture?: boolean;
+    disableSessionReplay?: boolean;
+    secureCookie?: boolean;
+    compressCookies?: boolean;
+    clearEventPropertiesOnNewUser?: boolean;
+    ingestServer?: string;
+    trackingServer?: string;
+    eventPropertiesStorageMedium?: string;
+    metadataStorageMedium?: string;
+    [key: string]: unknown;
+}
+/**
+ * Heap SDK surface — the subset of window.heap methods this destination uses.
+ * Mirrors the snippet-provided command queue so tests can mock each method.
+ */
+interface HeapSDK {
+    load: (appId: string, config?: HeapConfig) => void;
+    track: (event: string, properties?: Record<string, HeapPropertyValue>) => void;
+    identify: (identity: string) => void;
+    resetIdentity: () => void;
+    addUserProperties: (properties: Record<string, HeapPropertyValue>) => void;
+    addEventProperties: (properties: Record<string, HeapPropertyValue>) => void;
+    clearEventProperties: () => void;
+    startTracking: () => void;
+    stopTracking: () => void;
+    appid?: string;
+    config?: HeapConfig;
+    q?: unknown[][];
+}
+/**
+ * Settings (destination-level).
+ *
+ * appId is required (Heap Project Settings → App ID).
+ * identify/userProperties resolve every push to keep identity sticky.
+ */
+interface Settings {
+    /** Heap App ID (required). Find it in Project > Settings > App ID. */
+    appId: string;
+    /** Disable Heap auto text capture. Default: true. */
+    disableTextCapture?: boolean;
+    /** Disable Heap automatic pageview tracking. Default: true (walkerOS handles pageviews). */
+    disablePageviewAutocapture?: boolean;
+    /** Disable Heap session replay. */
+    disableSessionReplay?: boolean;
+    /** SSL-only cookies. */
+    secureCookie?: boolean;
+    /** Custom server endpoint (first-party proxy). */
+    ingestServer?: string;
+    /** Destination-level identity mapping. Resolves to a string for heap.identify(). */
+    identify?: Mapping$1.Value;
+    /** Destination-level user properties mapping. Resolves to object for heap.addUserProperties(). */
+    userProperties?: Mapping$1.Value;
+    /** Additional heap.load() config passthrough. */
+    heapConfig?: HeapConfig;
+}
+/**
+ * Env — optional override for the Heap SDK. Production leaves this
+ * undefined and the destination creates the snippet's command queue on
+ * window.heap. Tests provide a mock via env.window.heap = { ... }.
+ */
+interface Env extends DestinationWeb.Env {
+    window: {
+        heap: HeapSDK;
+    };
+}
+declare global {
+    interface Window {
+        heap?: HeapSDK;
+    }
+}
+
+/**
+ * Pre-init env — window.heap is a no-op queue until init wires it.
+ */
+declare const init: Env | undefined;
+/**
+ * Post-init env — window.heap methods are spy-able no-ops.
+ * Tests clone this and replace individual methods with jest.fn() for assertions.
+ */
+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 overrides.
+ * The test runner reads `settings` from the example and merges it on top
+ * of the fixed appId when registering the destination.
+ */
+type HeapStepExample = Flow.StepExample & {
+    settings?: Partial<Settings>;
+};
+/**
+ * Default event forwarding — every walkerOS event becomes
+ * heap.track(event.name, properties). With no mapping, properties is `{}`.
+ */
+declare const defaultEventForwarding: HeapStepExample;
+/**
+ * Rename + map event properties via rule.data.map.
+ * data resolves to { order_id, total, currency } → heap.track('purchase', props).
+ */
+declare const destinationLevelInclude: HeapStepExample;
+/**
+ * Destination-level settings.identify — heap.identify() resolves user.id,
+ * then the default heap.track() call fires.
+ */
+declare const destinationLevelIdentify: HeapStepExample;
+/**
+ * Per-event login identify — heap.identify() from data.email + user
+ * properties from the same rule. skip: true suppresses the track() call.
+ */
+declare const userLoginIdentify: HeapStepExample;
+/**
+ * User logout — heap.resetIdentity(). skip: true suppresses the track() call.
+ */
+declare const userLogoutReset: HeapStepExample;
+/**
+ * Event with user properties from mapping — heap.addUserProperties() fires,
+ * then the default heap.track() call.
+ */
+declare const eventWithUserProperties: HeapStepExample;
+/**
+ * Global event properties — heap.addEventProperties() sets persistent
+ * properties on all subsequent events. skip: true on this rule.
+ */
+declare const globalEventProperties: HeapStepExample;
+/**
+ * Consent revoked — on('consent') handler calls heap.stopTracking()
+ * when a required consent key is false.
+ */
+declare const consentRevokeStopTracking: HeapStepExample;
+/**
+ * Consent granted — on('consent') handler calls heap.startTracking()
+ * when all required consent keys are true.
+ */
+declare const consentGrantStartTracking: HeapStepExample;
+
+type step_HeapStepExample = HeapStepExample;
+declare const step_consentGrantStartTracking: typeof consentGrantStartTracking;
+declare const step_consentRevokeStopTracking: typeof consentRevokeStopTracking;
+declare const step_defaultEventForwarding: typeof defaultEventForwarding;
+declare const step_destinationLevelIdentify: typeof destinationLevelIdentify;
+declare const step_destinationLevelInclude: typeof destinationLevelInclude;
+declare const step_eventWithUserProperties: typeof eventWithUserProperties;
+declare const step_globalEventProperties: typeof globalEventProperties;
+declare const step_userLoginIdentify: typeof userLoginIdentify;
+declare const step_userLogoutReset: typeof userLogoutReset;
+declare namespace step {
+  export { type step_HeapStepExample as HeapStepExample, step_consentGrantStartTracking as consentGrantStartTracking, step_consentRevokeStopTracking as consentRevokeStopTracking, step_defaultEventForwarding as defaultEventForwarding, step_destinationLevelIdentify as destinationLevelIdentify, step_destinationLevelInclude as destinationLevelInclude, step_eventWithUserProperties as eventWithUserProperties, step_globalEventProperties as globalEventProperties, step_userLoginIdentify as userLoginIdentify, step_userLogoutReset as userLogoutReset };
+}
+
+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 };

package/dist/dev.d.ts

@@ -0,0 +1,207 @@
+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';
+
+declare const SettingsSchema: z.ZodObject<{
+    appId: z.ZodString;
+    disableTextCapture: z.ZodOptional<z.ZodBoolean>;
+    disablePageviewAutocapture: z.ZodOptional<z.ZodBoolean>;
+    disableSessionReplay: z.ZodOptional<z.ZodBoolean>;
+    secureCookie: z.ZodOptional<z.ZodBoolean>;
+    ingestServer: z.ZodOptional<z.ZodString>;
+    identify: z.ZodOptional<z.ZodUnknown>;
+    userProperties: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+type Settings$1 = z.infer<typeof SettingsSchema>;
+
+declare const MappingSchema: z.ZodObject<{
+    identify: z.ZodOptional<z.ZodUnknown>;
+    reset: z.ZodOptional<z.ZodUnknown>;
+    userProperties: z.ZodOptional<z.ZodUnknown>;
+    eventProperties: z.ZodOptional<z.ZodUnknown>;
+    clearEventProperties: 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 };
+}
+
+/** Property value types accepted by Heap SDK methods. */
+type HeapPropertyValue = string | number | boolean;
+/** Options accepted by heap.load() as the second argument. */
+interface HeapConfig {
+    disableTextCapture?: boolean;
+    disablePageviewAutocapture?: boolean;
+    disableSessionReplay?: boolean;
+    secureCookie?: boolean;
+    compressCookies?: boolean;
+    clearEventPropertiesOnNewUser?: boolean;
+    ingestServer?: string;
+    trackingServer?: string;
+    eventPropertiesStorageMedium?: string;
+    metadataStorageMedium?: string;
+    [key: string]: unknown;
+}
+/**
+ * Heap SDK surface — the subset of window.heap methods this destination uses.
+ * Mirrors the snippet-provided command queue so tests can mock each method.
+ */
+interface HeapSDK {
+    load: (appId: string, config?: HeapConfig) => void;
+    track: (event: string, properties?: Record<string, HeapPropertyValue>) => void;
+    identify: (identity: string) => void;
+    resetIdentity: () => void;
+    addUserProperties: (properties: Record<string, HeapPropertyValue>) => void;
+    addEventProperties: (properties: Record<string, HeapPropertyValue>) => void;
+    clearEventProperties: () => void;
+    startTracking: () => void;
+    stopTracking: () => void;
+    appid?: string;
+    config?: HeapConfig;
+    q?: unknown[][];
+}
+/**
+ * Settings (destination-level).
+ *
+ * appId is required (Heap Project Settings → App ID).
+ * identify/userProperties resolve every push to keep identity sticky.
+ */
+interface Settings {
+    /** Heap App ID (required). Find it in Project > Settings > App ID. */
+    appId: string;
+    /** Disable Heap auto text capture. Default: true. */
+    disableTextCapture?: boolean;
+    /** Disable Heap automatic pageview tracking. Default: true (walkerOS handles pageviews). */
+    disablePageviewAutocapture?: boolean;
+    /** Disable Heap session replay. */
+    disableSessionReplay?: boolean;
+    /** SSL-only cookies. */
+    secureCookie?: boolean;
+    /** Custom server endpoint (first-party proxy). */
+    ingestServer?: string;
+    /** Destination-level identity mapping. Resolves to a string for heap.identify(). */
+    identify?: Mapping$1.Value;
+    /** Destination-level user properties mapping. Resolves to object for heap.addUserProperties(). */
+    userProperties?: Mapping$1.Value;
+    /** Additional heap.load() config passthrough. */
+    heapConfig?: HeapConfig;
+}
+/**
+ * Env — optional override for the Heap SDK. Production leaves this
+ * undefined and the destination creates the snippet's command queue on
+ * window.heap. Tests provide a mock via env.window.heap = { ... }.
+ */
+interface Env extends DestinationWeb.Env {
+    window: {
+        heap: HeapSDK;
+    };
+}
+declare global {
+    interface Window {
+        heap?: HeapSDK;
+    }
+}
+
+/**
+ * Pre-init env — window.heap is a no-op queue until init wires it.
+ */
+declare const init: Env | undefined;
+/**
+ * Post-init env — window.heap methods are spy-able no-ops.
+ * Tests clone this and replace individual methods with jest.fn() for assertions.
+ */
+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 overrides.
+ * The test runner reads `settings` from the example and merges it on top
+ * of the fixed appId when registering the destination.
+ */
+type HeapStepExample = Flow.StepExample & {
+    settings?: Partial<Settings>;
+};
+/**
+ * Default event forwarding — every walkerOS event becomes
+ * heap.track(event.name, properties). With no mapping, properties is `{}`.
+ */
+declare const defaultEventForwarding: HeapStepExample;
+/**
+ * Rename + map event properties via rule.data.map.
+ * data resolves to { order_id, total, currency } → heap.track('purchase', props).
+ */
+declare const destinationLevelInclude: HeapStepExample;
+/**
+ * Destination-level settings.identify — heap.identify() resolves user.id,
+ * then the default heap.track() call fires.
+ */
+declare const destinationLevelIdentify: HeapStepExample;
+/**
+ * Per-event login identify — heap.identify() from data.email + user
+ * properties from the same rule. skip: true suppresses the track() call.
+ */
+declare const userLoginIdentify: HeapStepExample;
+/**
+ * User logout — heap.resetIdentity(). skip: true suppresses the track() call.
+ */
+declare const userLogoutReset: HeapStepExample;
+/**
+ * Event with user properties from mapping — heap.addUserProperties() fires,
+ * then the default heap.track() call.
+ */
+declare const eventWithUserProperties: HeapStepExample;
+/**
+ * Global event properties — heap.addEventProperties() sets persistent
+ * properties on all subsequent events. skip: true on this rule.
+ */
+declare const globalEventProperties: HeapStepExample;
+/**
+ * Consent revoked — on('consent') handler calls heap.stopTracking()
+ * when a required consent key is false.
+ */
+declare const consentRevokeStopTracking: HeapStepExample;
+/**
+ * Consent granted — on('consent') handler calls heap.startTracking()
+ * when all required consent keys are true.
+ */
+declare const consentGrantStartTracking: HeapStepExample;
+
+type step_HeapStepExample = HeapStepExample;
+declare const step_consentGrantStartTracking: typeof consentGrantStartTracking;
+declare const step_consentRevokeStopTracking: typeof consentRevokeStopTracking;
+declare const step_defaultEventForwarding: typeof defaultEventForwarding;
+declare const step_destinationLevelIdentify: typeof destinationLevelIdentify;
+declare const step_destinationLevelInclude: typeof destinationLevelInclude;
+declare const step_eventWithUserProperties: typeof eventWithUserProperties;
+declare const step_globalEventProperties: typeof globalEventProperties;
+declare const step_userLoginIdentify: typeof userLoginIdentify;
+declare const step_userLogoutReset: typeof userLogoutReset;
+declare namespace step {
+  export { type step_HeapStepExample as HeapStepExample, step_consentGrantStartTracking as consentGrantStartTracking, step_consentRevokeStopTracking as consentRevokeStopTracking, step_defaultEventForwarding as defaultEventForwarding, step_destinationLevelIdentify as destinationLevelIdentify, step_destinationLevelInclude as destinationLevelInclude, step_eventWithUserProperties as eventWithUserProperties, step_globalEventProperties as globalEventProperties, step_userLoginIdentify as userLoginIdentify, step_userLogoutReset as userLogoutReset };
+}
+
+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 };