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

package/dist/examples/index.d.mts

@@ -0,0 +1,206 @@
+import { Mapping, Flow } from '@walkeros/core';
+import { DestinationWeb } from '@walkeros/web-core';
+import { PostHogConfig, Properties } from 'posthog-js';
+
+/**
+ * Destination-level settings.
+ *
+ * PostHog's `PostHogConfig` interface has ~80 fields — extending the SDK type
+ * directly keeps IntelliSense complete and prevents drift. The destination adds:
+ *  - `apiKey` (required) — first arg to `posthog.init(...)`, NOT an init option
+ *  - `identify` — destination-level identity mapping
+ *  - `include` — event sections flattened into `capture()` properties
+ *  - `group` — destination-level group association
+ *  - `_state` — runtime state (not user-facing, mutated by init/push)
+ *
+ * All other walkerOS-specific mapping features live under mapping.settings
+ * (see Mapping interface below). Built-in PostHog features (session_recording,
+ * advanced_disable_flags, disable_surveys, capture_heatmaps, capture_exceptions,
+ * bootstrap, cookieless_mode, ...) are passthrough via PostHogConfig.
+ */
+interface Settings extends Partial<PostHogConfig> {
+    /** PostHog project API key (e.g. "phc_XXX"). First arg to posthog.init(). */
+    apiKey: string;
+    /** Destination-level identity mapping, resolved on first push. */
+    identify?: Mapping.Value;
+    /** Destination-level group association, resolved on first push. */
+    group?: Mapping.Value;
+    /** Runtime state — populated by init() and mutated by push(). Not user-facing. */
+    _state?: RuntimeState;
+}
+interface RuntimeState {
+    /** Last-resolved identity values, used to skip redundant identify/group calls. */
+    lastIdentity?: {
+        distinctId?: string;
+    };
+    lastGroup?: {
+        type?: string;
+        key?: string;
+    };
+}
+/**
+ * PostHog SDK surface — the subset of `posthog-js` the destination actually
+ * uses. Mirrors the real module's default singleton export shape. Tests mock
+ * via env.posthog to intercept every call.
+ */
+interface PostHogSDK {
+    init: (token: string, config?: Partial<PostHogConfig> & {
+        loaded?: (posthog: PostHogSDK) => void;
+    }, name?: string) => PostHogSDK;
+    capture: (eventName: string, properties?: Properties) => void;
+    identify: (distinctId?: string, userPropertiesToSet?: Properties, userPropertiesToSetOnce?: Properties) => void;
+    setPersonProperties: (userPropertiesToSet?: Properties, userPropertiesToSetOnce?: Properties) => void;
+    group: (groupType: string, groupKey: string, groupPropertiesToSet?: Properties) => void;
+    reset: (resetDeviceId?: boolean) => void;
+    opt_in_capturing: (options?: {
+        captureEventName?: string | null | false;
+        captureProperties?: Properties;
+    }) => void;
+    opt_out_capturing: () => void;
+}
+/**
+ * Env — optional SDK override. Production leaves this undefined and the
+ * destination falls back to the real `posthog-js` default export. Tests
+ * provide a mock via env.posthog = { ... }.
+ */
+interface Env extends DestinationWeb.Env {
+    posthog?: PostHogSDK;
+}
+
+/**
+ * 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 them
+ * into the base destination settings on top of the fixed apiKey.
+ */
+type PostHogStepExample = Flow.StepExample & {
+    settings?: Partial<Settings>;
+    configInclude?: string[];
+};
+/**
+ * Default event forwarding — every walkerOS event becomes
+ * posthog.capture(event.name, properties). With no mapping and no
+ * destination-level include, properties is `{}`.
+ */
+declare const defaultEventForwarding: PostHogStepExample;
+/**
+ * Wildcard ignore — walkerOS's standard way to drop events. The rule
+ * matches but does nothing. The destination fires zero SDK calls.
+ */
+declare const wildcardIgnored: PostHogStepExample;
+/**
+ * Destination-level settings.include flattens the walkerOS `data` section
+ * into prefixed capture() properties on every push.
+ */
+declare const destinationLevelInclude: PostHogStepExample;
+/**
+ * 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: PostHogStepExample;
+/**
+ * Destination-level settings.identify fires on the first push (once the
+ * state cache is empty). The destination calls posthog.identify() and
+ * tracks the resolved distinctId in runtime state; subsequent pushes
+ * with unchanged values do NOT re-fire identify().
+ *
+ * With NO $set/$set_once keys in the resolved object, posthog.identify
+ * is called with just the distinctId.
+ */
+declare const destinationLevelIdentify: PostHogStepExample;
+/**
+ * Per-event identify with the full PostHog identity vocabulary.
+ * This is the "user login" pattern: set a new distinctId and enrich
+ * person properties. `skip: true` suppresses the default posthog.capture()
+ * call because we're running identity side effects only.
+ *
+ * PostHog identify signature:
+ *   posthog.identify(distinctId, $set, $set_once)
+ */
+declare const userLoginIdentify: PostHogStepExample;
+/**
+ * Person-properties-only update — when the resolved identify object has
+ * NO `distinctId` key, the destination calls setPersonProperties($set, $set_once)
+ * instead of identify(). This is the "profile update" pattern: enrich
+ * user properties without changing identity.
+ *
+ * `skip` defaults to false here — we intentionally ALSO capture a
+ * "profile update" event so it shows up in PostHog's event stream.
+ */
+declare const profileUpdateSetPersonProperties: PostHogStepExample;
+/**
+ * User logout — reset: true fires posthog.reset(), which clears the
+ * distinct ID and generates a new anonymous one. `skip: true` because
+ * we're only running the reset side effect, no default capture().
+ */
+declare const userLogoutReset: PostHogStepExample;
+/**
+ * Group assignment + group properties. PostHog's group analytics (paid)
+ * aggregates events by company / team / project. The destination resolves
+ * `settings.group` to { type, key, properties? } and calls
+ * posthog.group(type, key, properties). `skip: true` keeps this a
+ * pure side-effect rule — no "company update" capture().
+ */
+declare const groupAssignmentWithProperties: PostHogStepExample;
+/**
+ * Order complete — PostHog has no dedicated revenue API. Revenue tracking
+ * is just a capture() call with the revenue properties in data. This
+ * example pairs `include: ["data", "globals"]` with a destination-level
+ * capture. The order total, shipping, currency, etc. all become
+ * data_* properties on the PostHog event.
+ */
+declare const orderCompleteWithInclude: PostHogStepExample;
+/**
+ * Consent revoked → posthog.opt_out_capturing(). The destination checks
+ * the consent key declared in config.consent (here "analytics") and
+ * toggles accordingly. opt_out_capturing() stops capture, session
+ * replay, AND survey rendering.
+ *
+ * Uses the canonical StepExample.command='consent' pattern: the test
+ * runner dispatches via elb('walker consent', in) instead of pushing
+ * an event.
+ */
+declare const consentRevokeOptOut: PostHogStepExample;
+/**
+ * Consent granted → posthog.opt_in_capturing(). Called without arguments
+ * by default (the SDK fires its own $opt_in event).
+ */
+declare const consentGrantOptIn: PostHogStepExample;
+
+type step_PostHogStepExample = PostHogStepExample;
+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_groupAssignmentWithProperties: typeof groupAssignmentWithProperties;
+declare const step_orderCompleteWithInclude: typeof orderCompleteWithInclude;
+declare const step_profileUpdateSetPersonProperties: typeof profileUpdateSetPersonProperties;
+declare const step_ruleIncludeReplaces: typeof ruleIncludeReplaces;
+declare const step_userLoginIdentify: typeof userLoginIdentify;
+declare const step_userLogoutReset: typeof userLogoutReset;
+declare const step_wildcardIgnored: typeof wildcardIgnored;
+declare namespace step {
+  export { type step_PostHogStepExample as PostHogStepExample, step_consentGrantOptIn as consentGrantOptIn, step_consentRevokeOptOut as consentRevokeOptOut, step_defaultEventForwarding as defaultEventForwarding, step_destinationLevelIdentify as destinationLevelIdentify, step_destinationLevelInclude as destinationLevelInclude, step_groupAssignmentWithProperties as groupAssignmentWithProperties, step_orderCompleteWithInclude as orderCompleteWithInclude, step_profileUpdateSetPersonProperties as profileUpdateSetPersonProperties, step_ruleIncludeReplaces as ruleIncludeReplaces, step_userLoginIdentify as userLoginIdentify, step_userLogoutReset as userLogoutReset, step_wildcardIgnored as wildcardIgnored };
+}
+
+export { env, step };

package/dist/examples/index.d.ts

@@ -0,0 +1,206 @@
+import { Mapping, Flow } from '@walkeros/core';
+import { DestinationWeb } from '@walkeros/web-core';
+import { PostHogConfig, Properties } from 'posthog-js';
+
+/**
+ * Destination-level settings.
+ *
+ * PostHog's `PostHogConfig` interface has ~80 fields — extending the SDK type
+ * directly keeps IntelliSense complete and prevents drift. The destination adds:
+ *  - `apiKey` (required) — first arg to `posthog.init(...)`, NOT an init option
+ *  - `identify` — destination-level identity mapping
+ *  - `include` — event sections flattened into `capture()` properties
+ *  - `group` — destination-level group association
+ *  - `_state` — runtime state (not user-facing, mutated by init/push)
+ *
+ * All other walkerOS-specific mapping features live under mapping.settings
+ * (see Mapping interface below). Built-in PostHog features (session_recording,
+ * advanced_disable_flags, disable_surveys, capture_heatmaps, capture_exceptions,
+ * bootstrap, cookieless_mode, ...) are passthrough via PostHogConfig.
+ */
+interface Settings extends Partial<PostHogConfig> {
+    /** PostHog project API key (e.g. "phc_XXX"). First arg to posthog.init(). */
+    apiKey: string;
+    /** Destination-level identity mapping, resolved on first push. */
+    identify?: Mapping.Value;
+    /** Destination-level group association, resolved on first push. */
+    group?: Mapping.Value;
+    /** Runtime state — populated by init() and mutated by push(). Not user-facing. */
+    _state?: RuntimeState;
+}
+interface RuntimeState {
+    /** Last-resolved identity values, used to skip redundant identify/group calls. */
+    lastIdentity?: {
+        distinctId?: string;
+    };
+    lastGroup?: {
+        type?: string;
+        key?: string;
+    };
+}
+/**
+ * PostHog SDK surface — the subset of `posthog-js` the destination actually
+ * uses. Mirrors the real module's default singleton export shape. Tests mock
+ * via env.posthog to intercept every call.
+ */
+interface PostHogSDK {
+    init: (token: string, config?: Partial<PostHogConfig> & {
+        loaded?: (posthog: PostHogSDK) => void;
+    }, name?: string) => PostHogSDK;
+    capture: (eventName: string, properties?: Properties) => void;
+    identify: (distinctId?: string, userPropertiesToSet?: Properties, userPropertiesToSetOnce?: Properties) => void;
+    setPersonProperties: (userPropertiesToSet?: Properties, userPropertiesToSetOnce?: Properties) => void;
+    group: (groupType: string, groupKey: string, groupPropertiesToSet?: Properties) => void;
+    reset: (resetDeviceId?: boolean) => void;
+    opt_in_capturing: (options?: {
+        captureEventName?: string | null | false;
+        captureProperties?: Properties;
+    }) => void;
+    opt_out_capturing: () => void;
+}
+/**
+ * Env — optional SDK override. Production leaves this undefined and the
+ * destination falls back to the real `posthog-js` default export. Tests
+ * provide a mock via env.posthog = { ... }.
+ */
+interface Env extends DestinationWeb.Env {
+    posthog?: PostHogSDK;
+}
+
+/**
+ * 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 them
+ * into the base destination settings on top of the fixed apiKey.
+ */
+type PostHogStepExample = Flow.StepExample & {
+    settings?: Partial<Settings>;
+    configInclude?: string[];
+};
+/**
+ * Default event forwarding — every walkerOS event becomes
+ * posthog.capture(event.name, properties). With no mapping and no
+ * destination-level include, properties is `{}`.
+ */
+declare const defaultEventForwarding: PostHogStepExample;
+/**
+ * Wildcard ignore — walkerOS's standard way to drop events. The rule
+ * matches but does nothing. The destination fires zero SDK calls.
+ */
+declare const wildcardIgnored: PostHogStepExample;
+/**
+ * Destination-level settings.include flattens the walkerOS `data` section
+ * into prefixed capture() properties on every push.
+ */
+declare const destinationLevelInclude: PostHogStepExample;
+/**
+ * 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: PostHogStepExample;
+/**
+ * Destination-level settings.identify fires on the first push (once the
+ * state cache is empty). The destination calls posthog.identify() and
+ * tracks the resolved distinctId in runtime state; subsequent pushes
+ * with unchanged values do NOT re-fire identify().
+ *
+ * With NO $set/$set_once keys in the resolved object, posthog.identify
+ * is called with just the distinctId.
+ */
+declare const destinationLevelIdentify: PostHogStepExample;
+/**
+ * Per-event identify with the full PostHog identity vocabulary.
+ * This is the "user login" pattern: set a new distinctId and enrich
+ * person properties. `skip: true` suppresses the default posthog.capture()
+ * call because we're running identity side effects only.
+ *
+ * PostHog identify signature:
+ *   posthog.identify(distinctId, $set, $set_once)
+ */
+declare const userLoginIdentify: PostHogStepExample;
+/**
+ * Person-properties-only update — when the resolved identify object has
+ * NO `distinctId` key, the destination calls setPersonProperties($set, $set_once)
+ * instead of identify(). This is the "profile update" pattern: enrich
+ * user properties without changing identity.
+ *
+ * `skip` defaults to false here — we intentionally ALSO capture a
+ * "profile update" event so it shows up in PostHog's event stream.
+ */
+declare const profileUpdateSetPersonProperties: PostHogStepExample;
+/**
+ * User logout — reset: true fires posthog.reset(), which clears the
+ * distinct ID and generates a new anonymous one. `skip: true` because
+ * we're only running the reset side effect, no default capture().
+ */
+declare const userLogoutReset: PostHogStepExample;
+/**
+ * Group assignment + group properties. PostHog's group analytics (paid)
+ * aggregates events by company / team / project. The destination resolves
+ * `settings.group` to { type, key, properties? } and calls
+ * posthog.group(type, key, properties). `skip: true` keeps this a
+ * pure side-effect rule — no "company update" capture().
+ */
+declare const groupAssignmentWithProperties: PostHogStepExample;
+/**
+ * Order complete — PostHog has no dedicated revenue API. Revenue tracking
+ * is just a capture() call with the revenue properties in data. This
+ * example pairs `include: ["data", "globals"]` with a destination-level
+ * capture. The order total, shipping, currency, etc. all become
+ * data_* properties on the PostHog event.
+ */
+declare const orderCompleteWithInclude: PostHogStepExample;
+/**
+ * Consent revoked → posthog.opt_out_capturing(). The destination checks
+ * the consent key declared in config.consent (here "analytics") and
+ * toggles accordingly. opt_out_capturing() stops capture, session
+ * replay, AND survey rendering.
+ *
+ * Uses the canonical StepExample.command='consent' pattern: the test
+ * runner dispatches via elb('walker consent', in) instead of pushing
+ * an event.
+ */
+declare const consentRevokeOptOut: PostHogStepExample;
+/**
+ * Consent granted → posthog.opt_in_capturing(). Called without arguments
+ * by default (the SDK fires its own $opt_in event).
+ */
+declare const consentGrantOptIn: PostHogStepExample;
+
+type step_PostHogStepExample = PostHogStepExample;
+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_groupAssignmentWithProperties: typeof groupAssignmentWithProperties;
+declare const step_orderCompleteWithInclude: typeof orderCompleteWithInclude;
+declare const step_profileUpdateSetPersonProperties: typeof profileUpdateSetPersonProperties;
+declare const step_ruleIncludeReplaces: typeof ruleIncludeReplaces;
+declare const step_userLoginIdentify: typeof userLoginIdentify;
+declare const step_userLogoutReset: typeof userLogoutReset;
+declare const step_wildcardIgnored: typeof wildcardIgnored;
+declare namespace step {
+  export { type step_PostHogStepExample as PostHogStepExample, step_consentGrantOptIn as consentGrantOptIn, step_consentRevokeOptOut as consentRevokeOptOut, step_defaultEventForwarding as defaultEventForwarding, step_destinationLevelIdentify as destinationLevelIdentify, step_destinationLevelInclude as destinationLevelInclude, step_groupAssignmentWithProperties as groupAssignmentWithProperties, step_orderCompleteWithInclude as orderCompleteWithInclude, step_profileUpdateSetPersonProperties as profileUpdateSetPersonProperties, step_ruleIncludeReplaces as ruleIncludeReplaces, step_userLoginIdentify as userLoginIdentify, step_userLogoutReset as userLogoutReset, step_wildcardIgnored as wildcardIgnored };
+}
+
+export { env, step };