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

package/README.md

@@ -0,0 +1,74 @@
+# @walkeros/web-destination-fullstory
+
+FullStory web destination for [walkerOS](https://github.com/elbwalker/walkerOS).
+Forwards events to FullStory via the official `@fullstory/browser` SDK v2 with
+support for custom events, user/page properties, identity, and consent.
+
+## Installation
+
+```bash
+npm install @walkeros/web-destination-fullstory
+```
+
+## Quick Start
+
+```json
+{
+  "destinations": {
+    "fullstory": {
+      "package": "@walkeros/web-destination-fullstory",
+      "config": {
+        "consent": { "analytics": true },
+        "settings": {
+          "orgId": "o-XXXXXX-na1"
+        }
+      }
+    }
+  }
+}
+```
+
+## Settings
+
+| Setting                    | Type         | Required | Description                                      |
+| -------------------------- | ------------ | -------- | ------------------------------------------------ |
+| `orgId`                    | string       | Yes      | FullStory organization ID                        |
+| `host`                     | string       | No       | Recording server host (proxy support)            |
+| `script`                   | string       | No       | Custom script CDN host                           |
+| `cookieDomain`             | string       | No       | Cookie domain override                           |
+| `debug`                    | boolean      | No       | Browser console debug logging                    |
+| `devMode`                  | boolean      | No       | Disable recording (dev environments)             |
+| `startCaptureManually`     | boolean      | No       | Delay capture until consent                      |
+| `namespace`                | string       | No       | Global FS identifier override                    |
+| `recordCrossDomainIFrames` | boolean      | No       | Cross-domain iframe recording                    |
+| `identify`                 | MappingValue | No       | Destination-level identity mapping               |
+| `consent`                  | Record       | No       | walkerOS consent key to FullStory action mapping |
+
+## Mapping Settings
+
+Per-event mapping settings control which FullStory methods are called:
+
+| Setting    | Effect                                      | Description                          |
+| ---------- | ------------------------------------------- | ------------------------------------ |
+| `identify` | Calls `setIdentity({ uid, properties })`    | Overrides destination-level identify |
+| `set`      | Calls `setProperties({ type, properties })` | User or page properties              |
+| `setType`  | Controls property scope                     | `'user'` (default) or `'page'`       |
+
+## Consent
+
+For GDPR compliance, use `startCaptureManually: true` and map consent:
+
+```json
+{
+  "settings": {
+    "orgId": "o-XXXXXX-na1",
+    "startCaptureManually": true,
+    "consent": {
+      "analytics": "capture"
+    }
+  }
+}
+```
+
+- `"capture"` controls `start`/`shutdown` (recording on/off)
+- `"consent"` controls `setIdentity({ consent })` flag

package/dist/dev.d.mts

@@ -0,0 +1,228 @@
+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<{
+    orgId: z.ZodString;
+    host: z.ZodOptional<z.ZodString>;
+    script: z.ZodOptional<z.ZodString>;
+    cookieDomain: z.ZodOptional<z.ZodString>;
+    debug: z.ZodOptional<z.ZodBoolean>;
+    devMode: z.ZodOptional<z.ZodBoolean>;
+    startCaptureManually: z.ZodOptional<z.ZodBoolean>;
+    namespace: z.ZodOptional<z.ZodString>;
+    recordCrossDomainIFrames: z.ZodOptional<z.ZodBoolean>;
+    identify: z.ZodOptional<z.ZodUnknown>;
+    consent: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+        capture: "capture";
+        consent: "consent";
+    }>>>;
+}, z.core.$strip>;
+type Settings$1 = z.infer<typeof SettingsSchema>;
+
+declare const MappingSchema: z.ZodObject<{
+    identify: z.ZodOptional<z.ZodUnknown>;
+    set: z.ZodOptional<z.ZodUnknown>;
+    setType: z.ZodOptional<z.ZodEnum<{
+        user: "user";
+        page: "page";
+    }>>;
+}, 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).
+ *
+ * orgId is the FullStory organization ID (e.g. "o-XXXXXX-na1").
+ * All SnippetOptions from @fullstory/browser are available as passthrough.
+ */
+interface Settings {
+    orgId: string;
+    host?: string;
+    script?: string;
+    cookieDomain?: string;
+    debug?: boolean;
+    devMode?: boolean;
+    startCaptureManually?: boolean;
+    namespace?: string;
+    recordCrossDomainIFrames?: boolean;
+    identify?: Mapping$1.Value;
+    consent?: Record<string, 'capture' | 'consent'>;
+}
+/**
+ * FullStory SDK surface -- the subset of @fullstory/browser methods this
+ * destination actually calls. Tests can mock each method individually.
+ *
+ * Uses V2 API only: FullStory('operationName', options).
+ */
+interface FullStorySDK {
+    init: (options: {
+        orgId: string;
+        host?: string;
+        script?: string;
+        cookieDomain?: string;
+        debug?: boolean;
+        devMode?: boolean;
+        startCaptureManually?: boolean;
+        namespace?: string;
+        recordCrossDomainIFrames?: boolean;
+    }) => void;
+    trackEvent: (options: {
+        name: string;
+        properties?: Record<string, unknown>;
+    }) => void;
+    setIdentity: (options: {
+        uid?: string | false;
+        anonymous?: boolean;
+        consent?: boolean;
+        properties?: Record<string, unknown>;
+    }) => void;
+    setProperties: (options: {
+        type: 'user' | 'page';
+        properties: Record<string, unknown>;
+    }) => void;
+    shutdown: () => void;
+    start: () => void;
+}
+/**
+ * Env -- optional override for the vendor SDK. Production leaves this
+ * undefined and the destination falls back to the real @fullstory/browser.
+ * Tests provide a mock via env.fullstory = { ... }.
+ */
+interface Env extends DestinationWeb.Env {
+    fullstory?: FullStorySDK;
+}
+
+/**
+ * Pre-init environment -- FullStory SDK methods are no-ops until init wires them.
+ */
+declare const init: Env | undefined;
+/**
+ * Post-init environment -- FullStory 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 that may carry destination-level settings overrides.
+ */
+type FullStoryStepExample = Flow.StepExample & {
+    settings?: Partial<Settings>;
+};
+/**
+ * Default event forwarding -- every walkerOS event becomes
+ * FullStory('trackEvent', { name, properties }). No mapping rule needed.
+ */
+declare const defaultEventForwarding: FullStoryStepExample;
+/**
+ * Wildcard ignore -- the event matches a mapping rule with ignore: true.
+ * The destination fires zero SDK calls.
+ */
+declare const wildcardIgnored: FullStoryStepExample;
+/**
+ * Event name mapping -- mapping.name renames the walkerOS event for FullStory.
+ */
+declare const mappedEventName: FullStoryStepExample;
+/**
+ * Per-event identify via mapping.settings.identify.
+ * Resolves { uid, properties } and calls FullStory('setIdentity', ...).
+ * Then fires the default trackEvent.
+ */
+declare const userLoginIdentify: FullStoryStepExample;
+/**
+ * Destination-level settings.identify -- fires setIdentity on every push.
+ * Uses user.id from the standard getEvent fixture.
+ */
+declare const destinationLevelIdentify: FullStoryStepExample;
+/**
+ * User properties via mapping.settings.set with default setType ('user').
+ * Calls FullStory('setProperties', { type: 'user', properties }).
+ */
+declare const setUserProperties: FullStoryStepExample;
+/**
+ * Page properties via mapping.settings.set with setType: 'page'.
+ * skip: true suppresses trackEvent -- useful for page views where
+ * FullStory already auto-captures navigation.
+ */
+declare const setPageProperties: FullStoryStepExample;
+/**
+ * Combined features -- identify the user, set user properties, then fire
+ * the event. Tests push execution order: identify -> setProperties -> trackEvent.
+ */
+declare const combinedFeatures: FullStoryStepExample;
+/**
+ * skip: true with identify -- mapping.skip suppresses trackEvent but
+ * still executes identify and set from the mapping rule.
+ */
+declare const skipWithIdentify: FullStoryStepExample;
+/**
+ * Consent grant -- settings.consent maps walkerOS consent key "analytics"
+ * to FullStory "capture" action. Granting consent calls FullStory('start').
+ *
+ * Uses command='consent' so the test runner dispatches via
+ * elb('walker consent', in) instead of pushing an event.
+ */
+declare const consentGrantCapture: FullStoryStepExample;
+/**
+ * Consent revoke -- revoking consent calls FullStory('shutdown').
+ */
+declare const consentRevokeCapture: FullStoryStepExample;
+/**
+ * Consent flag -- settings.consent maps walkerOS consent key to FullStory
+ * "consent" action. Granting calls setIdentity({ consent: true }).
+ */
+declare const consentGrantFlag: FullStoryStepExample;
+/**
+ * Consent flag revoke -- calls setIdentity({ consent: false }).
+ */
+declare const consentRevokeFlag: FullStoryStepExample;
+
+type step_FullStoryStepExample = FullStoryStepExample;
+declare const step_combinedFeatures: typeof combinedFeatures;
+declare const step_consentGrantCapture: typeof consentGrantCapture;
+declare const step_consentGrantFlag: typeof consentGrantFlag;
+declare const step_consentRevokeCapture: typeof consentRevokeCapture;
+declare const step_consentRevokeFlag: typeof consentRevokeFlag;
+declare const step_defaultEventForwarding: typeof defaultEventForwarding;
+declare const step_destinationLevelIdentify: typeof destinationLevelIdentify;
+declare const step_mappedEventName: typeof mappedEventName;
+declare const step_setPageProperties: typeof setPageProperties;
+declare const step_setUserProperties: typeof setUserProperties;
+declare const step_skipWithIdentify: typeof skipWithIdentify;
+declare const step_userLoginIdentify: typeof userLoginIdentify;
+declare const step_wildcardIgnored: typeof wildcardIgnored;
+declare namespace step {
+  export { type step_FullStoryStepExample as FullStoryStepExample, step_combinedFeatures as combinedFeatures, step_consentGrantCapture as consentGrantCapture, step_consentGrantFlag as consentGrantFlag, step_consentRevokeCapture as consentRevokeCapture, step_consentRevokeFlag as consentRevokeFlag, step_defaultEventForwarding as defaultEventForwarding, step_destinationLevelIdentify as destinationLevelIdentify, step_mappedEventName as mappedEventName, step_setPageProperties as setPageProperties, step_setUserProperties as setUserProperties, step_skipWithIdentify as skipWithIdentify, 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,228 @@
+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<{
+    orgId: z.ZodString;
+    host: z.ZodOptional<z.ZodString>;
+    script: z.ZodOptional<z.ZodString>;
+    cookieDomain: z.ZodOptional<z.ZodString>;
+    debug: z.ZodOptional<z.ZodBoolean>;
+    devMode: z.ZodOptional<z.ZodBoolean>;
+    startCaptureManually: z.ZodOptional<z.ZodBoolean>;
+    namespace: z.ZodOptional<z.ZodString>;
+    recordCrossDomainIFrames: z.ZodOptional<z.ZodBoolean>;
+    identify: z.ZodOptional<z.ZodUnknown>;
+    consent: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+        capture: "capture";
+        consent: "consent";
+    }>>>;
+}, z.core.$strip>;
+type Settings$1 = z.infer<typeof SettingsSchema>;
+
+declare const MappingSchema: z.ZodObject<{
+    identify: z.ZodOptional<z.ZodUnknown>;
+    set: z.ZodOptional<z.ZodUnknown>;
+    setType: z.ZodOptional<z.ZodEnum<{
+        user: "user";
+        page: "page";
+    }>>;
+}, 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).
+ *
+ * orgId is the FullStory organization ID (e.g. "o-XXXXXX-na1").
+ * All SnippetOptions from @fullstory/browser are available as passthrough.
+ */
+interface Settings {
+    orgId: string;
+    host?: string;
+    script?: string;
+    cookieDomain?: string;
+    debug?: boolean;
+    devMode?: boolean;
+    startCaptureManually?: boolean;
+    namespace?: string;
+    recordCrossDomainIFrames?: boolean;
+    identify?: Mapping$1.Value;
+    consent?: Record<string, 'capture' | 'consent'>;
+}
+/**
+ * FullStory SDK surface -- the subset of @fullstory/browser methods this
+ * destination actually calls. Tests can mock each method individually.
+ *
+ * Uses V2 API only: FullStory('operationName', options).
+ */
+interface FullStorySDK {
+    init: (options: {
+        orgId: string;
+        host?: string;
+        script?: string;
+        cookieDomain?: string;
+        debug?: boolean;
+        devMode?: boolean;
+        startCaptureManually?: boolean;
+        namespace?: string;
+        recordCrossDomainIFrames?: boolean;
+    }) => void;
+    trackEvent: (options: {
+        name: string;
+        properties?: Record<string, unknown>;
+    }) => void;
+    setIdentity: (options: {
+        uid?: string | false;
+        anonymous?: boolean;
+        consent?: boolean;
+        properties?: Record<string, unknown>;
+    }) => void;
+    setProperties: (options: {
+        type: 'user' | 'page';
+        properties: Record<string, unknown>;
+    }) => void;
+    shutdown: () => void;
+    start: () => void;
+}
+/**
+ * Env -- optional override for the vendor SDK. Production leaves this
+ * undefined and the destination falls back to the real @fullstory/browser.
+ * Tests provide a mock via env.fullstory = { ... }.
+ */
+interface Env extends DestinationWeb.Env {
+    fullstory?: FullStorySDK;
+}
+
+/**
+ * Pre-init environment -- FullStory SDK methods are no-ops until init wires them.
+ */
+declare const init: Env | undefined;
+/**
+ * Post-init environment -- FullStory 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 that may carry destination-level settings overrides.
+ */
+type FullStoryStepExample = Flow.StepExample & {
+    settings?: Partial<Settings>;
+};
+/**
+ * Default event forwarding -- every walkerOS event becomes
+ * FullStory('trackEvent', { name, properties }). No mapping rule needed.
+ */
+declare const defaultEventForwarding: FullStoryStepExample;
+/**
+ * Wildcard ignore -- the event matches a mapping rule with ignore: true.
+ * The destination fires zero SDK calls.
+ */
+declare const wildcardIgnored: FullStoryStepExample;
+/**
+ * Event name mapping -- mapping.name renames the walkerOS event for FullStory.
+ */
+declare const mappedEventName: FullStoryStepExample;
+/**
+ * Per-event identify via mapping.settings.identify.
+ * Resolves { uid, properties } and calls FullStory('setIdentity', ...).
+ * Then fires the default trackEvent.
+ */
+declare const userLoginIdentify: FullStoryStepExample;
+/**
+ * Destination-level settings.identify -- fires setIdentity on every push.
+ * Uses user.id from the standard getEvent fixture.
+ */
+declare const destinationLevelIdentify: FullStoryStepExample;
+/**
+ * User properties via mapping.settings.set with default setType ('user').
+ * Calls FullStory('setProperties', { type: 'user', properties }).
+ */
+declare const setUserProperties: FullStoryStepExample;
+/**
+ * Page properties via mapping.settings.set with setType: 'page'.
+ * skip: true suppresses trackEvent -- useful for page views where
+ * FullStory already auto-captures navigation.
+ */
+declare const setPageProperties: FullStoryStepExample;
+/**
+ * Combined features -- identify the user, set user properties, then fire
+ * the event. Tests push execution order: identify -> setProperties -> trackEvent.
+ */
+declare const combinedFeatures: FullStoryStepExample;
+/**
+ * skip: true with identify -- mapping.skip suppresses trackEvent but
+ * still executes identify and set from the mapping rule.
+ */
+declare const skipWithIdentify: FullStoryStepExample;
+/**
+ * Consent grant -- settings.consent maps walkerOS consent key "analytics"
+ * to FullStory "capture" action. Granting consent calls FullStory('start').
+ *
+ * Uses command='consent' so the test runner dispatches via
+ * elb('walker consent', in) instead of pushing an event.
+ */
+declare const consentGrantCapture: FullStoryStepExample;
+/**
+ * Consent revoke -- revoking consent calls FullStory('shutdown').
+ */
+declare const consentRevokeCapture: FullStoryStepExample;
+/**
+ * Consent flag -- settings.consent maps walkerOS consent key to FullStory
+ * "consent" action. Granting calls setIdentity({ consent: true }).
+ */
+declare const consentGrantFlag: FullStoryStepExample;
+/**
+ * Consent flag revoke -- calls setIdentity({ consent: false }).
+ */
+declare const consentRevokeFlag: FullStoryStepExample;
+
+type step_FullStoryStepExample = FullStoryStepExample;
+declare const step_combinedFeatures: typeof combinedFeatures;
+declare const step_consentGrantCapture: typeof consentGrantCapture;
+declare const step_consentGrantFlag: typeof consentGrantFlag;
+declare const step_consentRevokeCapture: typeof consentRevokeCapture;
+declare const step_consentRevokeFlag: typeof consentRevokeFlag;
+declare const step_defaultEventForwarding: typeof defaultEventForwarding;
+declare const step_destinationLevelIdentify: typeof destinationLevelIdentify;
+declare const step_mappedEventName: typeof mappedEventName;
+declare const step_setPageProperties: typeof setPageProperties;
+declare const step_setUserProperties: typeof setUserProperties;
+declare const step_skipWithIdentify: typeof skipWithIdentify;
+declare const step_userLoginIdentify: typeof userLoginIdentify;
+declare const step_wildcardIgnored: typeof wildcardIgnored;
+declare namespace step {
+  export { type step_FullStoryStepExample as FullStoryStepExample, step_combinedFeatures as combinedFeatures, step_consentGrantCapture as consentGrantCapture, step_consentGrantFlag as consentGrantFlag, step_consentRevokeCapture as consentRevokeCapture, step_consentRevokeFlag as consentRevokeFlag, step_defaultEventForwarding as defaultEventForwarding, step_destinationLevelIdentify as destinationLevelIdentify, step_mappedEventName as mappedEventName, step_setPageProperties as setPageProperties, step_setUserProperties as setUserProperties, step_skipWithIdentify as skipWithIdentify, 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 };