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

package/README.md

@@ -0,0 +1,172 @@
+<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>
+
+# Hotjar Destination for walkerOS
+
+[Source Code](https://github.com/elbwalker/walkerOS/tree/main/packages/web/destinations/hotjar)
+&bull;
+[NPM Package](https://www.npmjs.com/package/@walkeros/web-destination-hotjar)
+&bull; [Documentation](https://www.walkeros.io/docs/destinations/web/hotjar)
+
+This package forwards walkerOS events to [Hotjar](https://www.hotjar.com/) —
+session recordings, heatmaps, surveys, and on-page feedback. Built on the
+official [`@hotjar/browser`](https://www.npmjs.com/package/@hotjar/browser) SDK.
+
+walkerOS follows a **source → collector → destination** architecture. This
+Hotjar destination receives processed events from the walkerOS collector and
+forwards them as Hotjar events, identities, and SPA route notifications.
+
+## Features
+
+- **Default event forwarding** — every walkerOS event becomes
+  `Hotjar.event(name)` with no additional config
+- **Identity** — `Hotjar.identify(userId, attributes)` with userId extracted
+  from the resolved mapping value; remaining keys become user attributes
+- **SPA state change** — `Hotjar.stateChange(path)` for accurate heatmaps on
+  virtual page views in single-page applications
+- **Snippet injection** — `@hotjar/browser` handles script loading, including
+  CSP `nonce` and debug mode
+
+## Installation
+
+```sh
+npm install @walkeros/web-destination-hotjar
+```
+
+## Quick Start
+
+```typescript
+import { startFlow } from '@walkeros/collector';
+import { destinationHotjar } from '@walkeros/web-destination-hotjar';
+
+await startFlow({
+  destinations: {
+    hotjar: {
+      code: destinationHotjar,
+      config: {
+        settings: {
+          siteId: 1234567, // your Hotjar site ID
+        },
+      },
+    },
+  },
+});
+```
+
+## Configuration
+
+### Settings (destination-level)
+
+| Name            | Type            | Description                                                                                            | Required |
+| --------------- | --------------- | ------------------------------------------------------------------------------------------------------ | -------- |
+| `siteId`        | `number`        | Hotjar site ID (numeric, from dashboard Settings)                                                      | Yes      |
+| `hotjarVersion` | `number`        | Hotjar snippet version. Defaults to `6`. Override only if Hotjar releases a new version.               | No       |
+| `debug`         | `boolean`       | Enable Hotjar debug mode for development troubleshooting                                               | No       |
+| `nonce`         | `string`        | CSP nonce for the injected Hotjar script tag (required with strict Content-Security-Policy)            | No       |
+| `identify`      | `Mapping.Value` | Destination-level identity mapping; resolves to `{ userId, ...attributes }` for `Hotjar.identify(...)` | No       |
+
+### Mapping (`rule.settings`)
+
+| Name          | Type            | Description                                                                                                  |
+| ------------- | --------------- | ------------------------------------------------------------------------------------------------------------ |
+| `identify`    | `Mapping.Value` | Per-event identity override; resolves to `{ userId, ...attributes }` → `Hotjar.identify(userId, attributes)` |
+| `stateChange` | `Mapping.Value` | SPA route change; resolves to a relative path string → `Hotjar.stateChange(path)`                            |
+
+Standard mapping features also apply:
+
+- `name` — rename the forwarded event (`Hotjar.event(<new name>)`)
+- `skip` — suppress the default `Hotjar.event(...)` call while still running
+  `identify` / `stateChange`
+- `ignore` — drop the event entirely (no calls produced)
+
+## Event Forwarding
+
+Hotjar's `event(actionName)` API is name-only — no properties, no payload. The
+destination forwards the walkerOS `event.name` (e.g. `"order complete"`) by
+default. Rename with `mapping.name`:
+
+```typescript
+mapping: {
+  order: {
+    complete: {
+      name: 'completed_purchase',
+    },
+  },
+}
+```
+
+## Identity
+
+Hotjar recommends calling `identify()` on every page load so subsequent events
+are associated with the right user. Configure at the destination level:
+
+```typescript
+settings: {
+  siteId: 1234567,
+  identify: {
+    map: {
+      userId: 'user.id',
+      plan: 'user.plan',
+    },
+  },
+}
+```
+
+The resolved object's `userId` becomes the first positional argument; every
+other key becomes a user attribute (Hotjar accepts `string | number | boolean`).
+Non-primitive values are skipped.
+
+Per-event identity overrides destination-level identity via
+`mapping.settings.identify`.
+
+## SPA State Change
+
+For single-page applications, fire `Hotjar.stateChange(path)` on route changes
+so heatmaps aggregate by virtual URL. Typical pattern: hook into your router and
+emit a walkerOS event:
+
+```typescript
+mapping: {
+  page: {
+    view: {
+      skip: true, // Suppress default Hotjar.event('page view')
+      settings: {
+        stateChange: 'data.id', // Resolves to the new path
+      },
+    },
+  },
+}
+```
+
+## Consent
+
+Hotjar has no runtime consent API. Consent is gated at the walkerOS level via
+`config.consent`:
+
+```typescript
+destinations: {
+  hotjar: {
+    code: destinationHotjar,
+    config: {
+      consent: { marketing: true },
+      settings: { siteId: 1234567 },
+    },
+  },
+}
+```
+
+Unconsented events are blocked by the collector before reaching the destination.
+
+## 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,157 @@
+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<{
+    siteId: z.ZodNumber;
+    hotjarVersion: z.ZodOptional<z.ZodNumber>;
+    debug: z.ZodOptional<z.ZodBoolean>;
+    nonce: z.ZodOptional<z.ZodString>;
+    identify: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+type Settings$1 = z.infer<typeof SettingsSchema>;
+
+declare const MappingSchema: z.ZodObject<{
+    identify: z.ZodOptional<z.ZodUnknown>;
+    stateChange: 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 };
+}
+
+/**
+ * Settings (destination-level).
+ *
+ * siteId is the numeric Hotjar site ID from the dashboard.
+ * identify resolves to { userId, ...attributes } for Hotjar.identify().
+ */
+interface Settings {
+    siteId: number;
+    hotjarVersion?: number;
+    debug?: boolean;
+    nonce?: string;
+    identify?: Mapping$1.Value;
+}
+/**
+ * Hotjar SDK surface -- the subset of @hotjar/browser methods this
+ * destination uses. Mirrors the default export so tests can mock
+ * each method individually.
+ */
+interface HotjarSDK {
+    init: (hotjarId: number, hotjarVersion: number, opts?: {
+        debug?: boolean;
+        nonce?: string;
+    }) => boolean;
+    event: (actionName: string) => boolean;
+    identify: (userId: string | null, userInfo: Record<string, string | number | Date | boolean>) => boolean;
+    stateChange: (relativePath: string) => boolean;
+    isReady: () => boolean;
+}
+/**
+ * Env -- optional override for the vendor SDK. Production leaves this
+ * undefined and the destination falls back to the real @hotjar/browser
+ * default export. Tests provide a mock via env.hotjar = { ... }.
+ */
+interface Env extends DestinationWeb.Env {
+    hotjar?: HotjarSDK;
+}
+
+/**
+ * Pre-init environment -- Hotjar SDK methods are no-ops until init wires them.
+ */
+declare const init: Env | undefined;
+/**
+ * Post-init environment -- Hotjar SDK 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 };
+}
+
+/**
+ * Extended step example allowing destination-level settings overrides.
+ */
+type HotjarStepExample = Flow.StepExample & {
+    settings?: Partial<Settings>;
+};
+/**
+ * Default event forwarding -- every walkerOS event becomes Hotjar.event(name).
+ * No mapping rule; the destination's default push behavior fires.
+ */
+declare const defaultEventForwarding: HotjarStepExample;
+/**
+ * Wildcard ignore pattern -- suppresses noisy events.
+ * The destination must produce zero calls.
+ */
+declare const wildcardIgnored: HotjarStepExample;
+/**
+ * Renamed event via mapping.name -- order complete becomes completed_purchase.
+ */
+declare const renamedEvent: HotjarStepExample;
+/**
+ * Per-event identity via mapping.settings.identify.
+ * Resolves { userId, ...attributes } -> Hotjar.identify(userId, attributes).
+ * Identify fires before event per Hotjar's guidance.
+ */
+declare const userLoginIdentify: HotjarStepExample;
+/**
+ * Destination-level settings.identify -- fires on every push.
+ * Hotjar recommends calling identify() on every page load.
+ */
+declare const destinationLevelIdentify: HotjarStepExample;
+/**
+ * SPA state change -- stateChange mapping resolves to path string.
+ * skip=true suppresses the default Hotjar.event() call.
+ */
+declare const pageViewStateChange: HotjarStepExample;
+/**
+ * Combined features -- identify + renamed event on the same push.
+ * Execution order: identify -> event.
+ */
+declare const combinedFeatures: HotjarStepExample;
+/**
+ * mapping.skip -- suppresses the default Hotjar.event() call. No other
+ * settings active, so the destination produces zero calls.
+ */
+declare const pageViewSkip: HotjarStepExample;
+
+type step_HotjarStepExample = HotjarStepExample;
+declare const step_combinedFeatures: typeof combinedFeatures;
+declare const step_defaultEventForwarding: typeof defaultEventForwarding;
+declare const step_destinationLevelIdentify: typeof destinationLevelIdentify;
+declare const step_pageViewSkip: typeof pageViewSkip;
+declare const step_pageViewStateChange: typeof pageViewStateChange;
+declare const step_renamedEvent: typeof renamedEvent;
+declare const step_userLoginIdentify: typeof userLoginIdentify;
+declare const step_wildcardIgnored: typeof wildcardIgnored;
+declare namespace step {
+  export { type step_HotjarStepExample as HotjarStepExample, step_combinedFeatures as combinedFeatures, step_defaultEventForwarding as defaultEventForwarding, step_destinationLevelIdentify as destinationLevelIdentify, step_pageViewSkip as pageViewSkip, step_pageViewStateChange as pageViewStateChange, step_renamedEvent as renamedEvent, step_userLoginIdentify as userLoginIdentify, 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 };

package/dist/dev.d.ts

@@ -0,0 +1,157 @@
+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<{
+    siteId: z.ZodNumber;
+    hotjarVersion: z.ZodOptional<z.ZodNumber>;
+    debug: z.ZodOptional<z.ZodBoolean>;
+    nonce: z.ZodOptional<z.ZodString>;
+    identify: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+type Settings$1 = z.infer<typeof SettingsSchema>;
+
+declare const MappingSchema: z.ZodObject<{
+    identify: z.ZodOptional<z.ZodUnknown>;
+    stateChange: 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 };
+}
+
+/**
+ * Settings (destination-level).
+ *
+ * siteId is the numeric Hotjar site ID from the dashboard.
+ * identify resolves to { userId, ...attributes } for Hotjar.identify().
+ */
+interface Settings {
+    siteId: number;
+    hotjarVersion?: number;
+    debug?: boolean;
+    nonce?: string;
+    identify?: Mapping$1.Value;
+}
+/**
+ * Hotjar SDK surface -- the subset of @hotjar/browser methods this
+ * destination uses. Mirrors the default export so tests can mock
+ * each method individually.
+ */
+interface HotjarSDK {
+    init: (hotjarId: number, hotjarVersion: number, opts?: {
+        debug?: boolean;
+        nonce?: string;
+    }) => boolean;
+    event: (actionName: string) => boolean;
+    identify: (userId: string | null, userInfo: Record<string, string | number | Date | boolean>) => boolean;
+    stateChange: (relativePath: string) => boolean;
+    isReady: () => boolean;
+}
+/**
+ * Env -- optional override for the vendor SDK. Production leaves this
+ * undefined and the destination falls back to the real @hotjar/browser
+ * default export. Tests provide a mock via env.hotjar = { ... }.
+ */
+interface Env extends DestinationWeb.Env {
+    hotjar?: HotjarSDK;
+}
+
+/**
+ * Pre-init environment -- Hotjar SDK methods are no-ops until init wires them.
+ */
+declare const init: Env | undefined;
+/**
+ * Post-init environment -- Hotjar SDK 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 };
+}
+
+/**
+ * Extended step example allowing destination-level settings overrides.
+ */
+type HotjarStepExample = Flow.StepExample & {
+    settings?: Partial<Settings>;
+};
+/**
+ * Default event forwarding -- every walkerOS event becomes Hotjar.event(name).
+ * No mapping rule; the destination's default push behavior fires.
+ */
+declare const defaultEventForwarding: HotjarStepExample;
+/**
+ * Wildcard ignore pattern -- suppresses noisy events.
+ * The destination must produce zero calls.
+ */
+declare const wildcardIgnored: HotjarStepExample;
+/**
+ * Renamed event via mapping.name -- order complete becomes completed_purchase.
+ */
+declare const renamedEvent: HotjarStepExample;
+/**
+ * Per-event identity via mapping.settings.identify.
+ * Resolves { userId, ...attributes } -> Hotjar.identify(userId, attributes).
+ * Identify fires before event per Hotjar's guidance.
+ */
+declare const userLoginIdentify: HotjarStepExample;
+/**
+ * Destination-level settings.identify -- fires on every push.
+ * Hotjar recommends calling identify() on every page load.
+ */
+declare const destinationLevelIdentify: HotjarStepExample;
+/**
+ * SPA state change -- stateChange mapping resolves to path string.
+ * skip=true suppresses the default Hotjar.event() call.
+ */
+declare const pageViewStateChange: HotjarStepExample;
+/**
+ * Combined features -- identify + renamed event on the same push.
+ * Execution order: identify -> event.
+ */
+declare const combinedFeatures: HotjarStepExample;
+/**
+ * mapping.skip -- suppresses the default Hotjar.event() call. No other
+ * settings active, so the destination produces zero calls.
+ */
+declare const pageViewSkip: HotjarStepExample;
+
+type step_HotjarStepExample = HotjarStepExample;
+declare const step_combinedFeatures: typeof combinedFeatures;
+declare const step_defaultEventForwarding: typeof defaultEventForwarding;
+declare const step_destinationLevelIdentify: typeof destinationLevelIdentify;
+declare const step_pageViewSkip: typeof pageViewSkip;
+declare const step_pageViewStateChange: typeof pageViewStateChange;
+declare const step_renamedEvent: typeof renamedEvent;
+declare const step_userLoginIdentify: typeof userLoginIdentify;
+declare const step_wildcardIgnored: typeof wildcardIgnored;
+declare namespace step {
+  export { type step_HotjarStepExample as HotjarStepExample, step_combinedFeatures as combinedFeatures, step_defaultEventForwarding as defaultEventForwarding, step_destinationLevelIdentify as destinationLevelIdentify, step_pageViewSkip as pageViewSkip, step_pageViewStateChange as pageViewStateChange, step_renamedEvent as renamedEvent, step_userLoginIdentify as userLoginIdentify, 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 };