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

package/dist/examples/index.d.mts

@@ -0,0 +1,234 @@
+import { Mapping, Flow } from '@walkeros/core';
+import { DestinationWeb } from '@walkeros/web-core';
+import { AnalyticsBrowserSettings, InitOptions } from '@segment/analytics-next';
+
+/**
+ * Destination-level settings.
+ *
+ * Extends Segment's `InitOptions` (minus the `group` key which clashes with
+ * walkerOS's own `group` mapping) so every passthrough option (cookie,
+ * storage, integrations, plan, etc.) keeps IntelliSense intact. walkerOS
+ * adds:
+ *  - `apiKey` (required) — maps to `writeKey` in `AnalyticsBrowser.load()`
+ *  - `identify` — destination-level identity mapping (Segment `identify()`)
+ *  - `group` — destination-level group mapping (Segment `group()`)
+ *  - `include` — event sections flattened into track `properties`
+ *  - `consent` — walkerOS consent key → Segment category name mapping
+ *  - `_state` — runtime state (not user-facing, mutated by init/push)
+ */
+interface Settings extends Omit<InitOptions, 'group'> {
+    /** Segment write key. Maps to `writeKey` in the load() settings arg. */
+    apiKey: string;
+    /** walkerOS mapping value resolving to an identity object (userId, traits, anonymousId). */
+    identify?: Mapping.Value;
+    /** walkerOS mapping value resolving to a group object (groupId, traits). */
+    group?: Mapping.Value;
+    /**
+     * Mapping from walkerOS consent keys → Segment `categoryPreferences` keys.
+     * Example: { marketing: "Advertising", analytics: "Analytics" }
+     * If omitted, walkerOS keys are forwarded 1:1.
+     */
+    consent?: Record<string, string>;
+    /** Runtime state — populated by init() and mutated by push(). Not user-facing. */
+    _state?: RuntimeState;
+}
+interface RuntimeState {
+    /** Last-set identity values, used to skip redundant identify() calls. */
+    lastIdentity?: {
+        userId?: string;
+        anonymousId?: string;
+        traitsHash?: string;
+    };
+    /** Last-set group assignment, used to skip redundant group() calls. */
+    lastGroup?: {
+        groupId?: string;
+        traitsHash?: string;
+    };
+    /** Holds the AnalyticsBrowser instance created in init(). */
+    analytics?: SegmentAnalytics;
+    /** True once load() has been called (may be deferred pending consent). */
+    loaded?: boolean;
+}
+/**
+ * Segment SDK surface — the subset of @segment/analytics-next the
+ * destination actually uses. Mirrors the AnalyticsBrowser instance shape
+ * so tests can mock each method individually via env.analytics.
+ */
+interface SegmentAnalytics {
+    track: (event: string, properties?: Record<string, unknown>, options?: SegmentEventOptions) => Promise<unknown> | void;
+    identify: (userId?: string | Record<string, unknown>, traits?: Record<string, unknown>, options?: SegmentEventOptions) => Promise<unknown> | void;
+    group: (groupId: string, traits?: Record<string, unknown>, options?: SegmentEventOptions) => Promise<unknown> | void;
+    page: (category?: string | null, name?: string | null, properties?: Record<string, unknown>, options?: SegmentEventOptions) => Promise<unknown> | void;
+    alias: (to: string, from?: string, options?: SegmentEventOptions) => Promise<unknown> | void;
+    reset: () => Promise<unknown> | void;
+    setAnonymousId: (id: string) => Promise<unknown> | void;
+}
+/**
+ * Segment event options — the fourth argument to track/identify/group/page
+ * that carries context and integration overrides. The destination uses
+ * this to stamp consent context on every event.
+ */
+interface SegmentEventOptions {
+    context?: {
+        consent?: {
+            categoryPreferences?: Record<string, boolean>;
+        };
+        [key: string]: unknown;
+    };
+    integrations?: Record<string, boolean | Record<string, unknown>>;
+}
+/**
+ * The module namespace used for `env?.analytics ?? realSegment`.
+ * AnalyticsBrowser is the class; tests mock with a factory that returns
+ * an object matching SegmentAnalytics.
+ *
+ * Task 1 verified: `AnalyticsBrowser.load(settings, options)` returns an
+ * `AnalyticsBrowser` instance **synchronously**. The instance buffers
+ * method calls until the internal load promise resolves.
+ */
+interface SegmentSDK {
+    load: (settings: AnalyticsBrowserSettings, options?: InitOptions) => SegmentAnalytics;
+}
+/**
+ * Env — optional SDK override. Production leaves this undefined and the
+ * destination falls back to the real @segment/analytics-next module.
+ * Tests provide a mock via env.analytics = { ... }.
+ */
+interface Env extends DestinationWeb.Env {
+    analytics?: SegmentSDK;
+}
+
+declare const init: Env | undefined;
+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 merges this on top of a base { apiKey: 'test-project' }.
+ */
+type SegmentStepExample = Flow.StepExample & {
+    settings?: Partial<Settings>;
+    configInclude?: string[];
+};
+/**
+ * Default event forwarding — every walkerOS event becomes
+ * analytics.track(event.name, properties). With no mapping and no
+ * destination-level include, properties is `{}`.
+ */
+declare const defaultEventForwarding: SegmentStepExample;
+/**
+ * Wildcard ignore — walkerOS's standard way to drop events. The rule
+ * matches but does nothing. The destination fires zero SDK calls.
+ */
+declare const wildcardIgnored: SegmentStepExample;
+/**
+ * Destination-level settings.include flattens the walkerOS `data` section
+ * into prefixed properties on every push.
+ */
+declare const destinationLevelInclude: SegmentStepExample;
+/**
+ * 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: SegmentStepExample;
+/**
+ * Destination-level settings.identify fires on the first push. The
+ * destination resolves the mapping, calls analytics.identify(userId),
+ * and records the value in runtime state. Subsequent pushes with the
+ * same userId do NOT re-fire identify().
+ */
+declare const destinationLevelIdentify: SegmentStepExample;
+/**
+ * Per-event identify with traits — the canonical "user login" pattern.
+ * skip: true suppresses the default analytics.track() call because we're
+ * running identity side effects only. Matches Segment Spec reserved traits
+ * (email, name, plan, company) so downstream destinations recognize them.
+ */
+declare const userLoginIdentify: SegmentStepExample;
+/**
+ * Profile update — omit userId. Segment's SDK uses the currently stored
+ * userId and merges the traits into the existing trait set.
+ */
+declare const profileUpdateTraitsOnly: SegmentStepExample;
+/**
+ * User logout — reset: true fires analytics.reset(), which clears userId,
+ * anonymousId, traits, and generates a new anonymous ID.
+ * skip: true because we're only running the reset side effect.
+ */
+declare const userLogoutReset: SegmentStepExample;
+/**
+ * Per-event group assignment — company update event attaches the user
+ * to a company and sets the company's traits in one call.
+ */
+declare const companyUpdateGroup: SegmentStepExample;
+/**
+ * Explicit page() call — the canonical Segment pattern for page views.
+ * skip: true suppresses the default track() call; settings.page fires
+ * analytics.page(category, name, properties) instead.
+ */
+declare const pageViewAsPage: SegmentStepExample;
+/**
+ * Minimal page() call — settings.page: true produces an empty
+ * analytics.page() relying entirely on SDK auto-collection.
+ */
+declare const pageViewMinimal: SegmentStepExample;
+/**
+ * Segment ecommerce spec — Order Completed event. One track() call with
+ * a products array. Uses mapping.name to produce the Segment Spec name
+ * and mapping.data to build the properties object including the nested
+ * products loop. The loop filters via condition to products with prices.
+ */
+declare const orderCompletedEcommerce: SegmentStepExample;
+/**
+ * Consent context forwarding — when the event has consent state,
+ * the destination automatically stamps every track/identify/group/page
+ * call with context.consent.categoryPreferences. settings.consent
+ * remaps walkerOS keys to Segment category names.
+ */
+declare const consentContextForwarded: SegmentStepExample;
+/**
+ * Consent granted → deferred load fires for the first time. The
+ * destination was initialized with consent requirement; on the walker
+ * consent command it calls analytics.load(writeKey, initOptions).
+ *
+ * Uses the canonical StepExample.command='consent' pattern. The full
+ * call shape includes both the settings arg and the initOptions arg.
+ */
+declare const consentGrantDeferredLoad: SegmentStepExample;
+/**
+ * Consent revoked → no SDK call. The walkerOS consent gate handles
+ * blocking subsequent events. The destination's on('consent') handler
+ * is a no-op on revocation (Segment has no opt-out method).
+ */
+declare const consentRevokeNoOp: SegmentStepExample;
+
+type step_SegmentStepExample = SegmentStepExample;
+declare const step_companyUpdateGroup: typeof companyUpdateGroup;
+declare const step_consentContextForwarded: typeof consentContextForwarded;
+declare const step_consentGrantDeferredLoad: typeof consentGrantDeferredLoad;
+declare const step_consentRevokeNoOp: typeof consentRevokeNoOp;
+declare const step_defaultEventForwarding: typeof defaultEventForwarding;
+declare const step_destinationLevelIdentify: typeof destinationLevelIdentify;
+declare const step_destinationLevelInclude: typeof destinationLevelInclude;
+declare const step_orderCompletedEcommerce: typeof orderCompletedEcommerce;
+declare const step_pageViewAsPage: typeof pageViewAsPage;
+declare const step_pageViewMinimal: typeof pageViewMinimal;
+declare const step_profileUpdateTraitsOnly: typeof profileUpdateTraitsOnly;
+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_SegmentStepExample as SegmentStepExample, step_companyUpdateGroup as companyUpdateGroup, step_consentContextForwarded as consentContextForwarded, step_consentGrantDeferredLoad as consentGrantDeferredLoad, step_consentRevokeNoOp as consentRevokeNoOp, step_defaultEventForwarding as defaultEventForwarding, step_destinationLevelIdentify as destinationLevelIdentify, step_destinationLevelInclude as destinationLevelInclude, step_orderCompletedEcommerce as orderCompletedEcommerce, step_pageViewAsPage as pageViewAsPage, step_pageViewMinimal as pageViewMinimal, step_profileUpdateTraitsOnly as profileUpdateTraitsOnly, 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,234 @@
+import { Mapping, Flow } from '@walkeros/core';
+import { DestinationWeb } from '@walkeros/web-core';
+import { AnalyticsBrowserSettings, InitOptions } from '@segment/analytics-next';
+
+/**
+ * Destination-level settings.
+ *
+ * Extends Segment's `InitOptions` (minus the `group` key which clashes with
+ * walkerOS's own `group` mapping) so every passthrough option (cookie,
+ * storage, integrations, plan, etc.) keeps IntelliSense intact. walkerOS
+ * adds:
+ *  - `apiKey` (required) — maps to `writeKey` in `AnalyticsBrowser.load()`
+ *  - `identify` — destination-level identity mapping (Segment `identify()`)
+ *  - `group` — destination-level group mapping (Segment `group()`)
+ *  - `include` — event sections flattened into track `properties`
+ *  - `consent` — walkerOS consent key → Segment category name mapping
+ *  - `_state` — runtime state (not user-facing, mutated by init/push)
+ */
+interface Settings extends Omit<InitOptions, 'group'> {
+    /** Segment write key. Maps to `writeKey` in the load() settings arg. */
+    apiKey: string;
+    /** walkerOS mapping value resolving to an identity object (userId, traits, anonymousId). */
+    identify?: Mapping.Value;
+    /** walkerOS mapping value resolving to a group object (groupId, traits). */
+    group?: Mapping.Value;
+    /**
+     * Mapping from walkerOS consent keys → Segment `categoryPreferences` keys.
+     * Example: { marketing: "Advertising", analytics: "Analytics" }
+     * If omitted, walkerOS keys are forwarded 1:1.
+     */
+    consent?: Record<string, string>;
+    /** Runtime state — populated by init() and mutated by push(). Not user-facing. */
+    _state?: RuntimeState;
+}
+interface RuntimeState {
+    /** Last-set identity values, used to skip redundant identify() calls. */
+    lastIdentity?: {
+        userId?: string;
+        anonymousId?: string;
+        traitsHash?: string;
+    };
+    /** Last-set group assignment, used to skip redundant group() calls. */
+    lastGroup?: {
+        groupId?: string;
+        traitsHash?: string;
+    };
+    /** Holds the AnalyticsBrowser instance created in init(). */
+    analytics?: SegmentAnalytics;
+    /** True once load() has been called (may be deferred pending consent). */
+    loaded?: boolean;
+}
+/**
+ * Segment SDK surface — the subset of @segment/analytics-next the
+ * destination actually uses. Mirrors the AnalyticsBrowser instance shape
+ * so tests can mock each method individually via env.analytics.
+ */
+interface SegmentAnalytics {
+    track: (event: string, properties?: Record<string, unknown>, options?: SegmentEventOptions) => Promise<unknown> | void;
+    identify: (userId?: string | Record<string, unknown>, traits?: Record<string, unknown>, options?: SegmentEventOptions) => Promise<unknown> | void;
+    group: (groupId: string, traits?: Record<string, unknown>, options?: SegmentEventOptions) => Promise<unknown> | void;
+    page: (category?: string | null, name?: string | null, properties?: Record<string, unknown>, options?: SegmentEventOptions) => Promise<unknown> | void;
+    alias: (to: string, from?: string, options?: SegmentEventOptions) => Promise<unknown> | void;
+    reset: () => Promise<unknown> | void;
+    setAnonymousId: (id: string) => Promise<unknown> | void;
+}
+/**
+ * Segment event options — the fourth argument to track/identify/group/page
+ * that carries context and integration overrides. The destination uses
+ * this to stamp consent context on every event.
+ */
+interface SegmentEventOptions {
+    context?: {
+        consent?: {
+            categoryPreferences?: Record<string, boolean>;
+        };
+        [key: string]: unknown;
+    };
+    integrations?: Record<string, boolean | Record<string, unknown>>;
+}
+/**
+ * The module namespace used for `env?.analytics ?? realSegment`.
+ * AnalyticsBrowser is the class; tests mock with a factory that returns
+ * an object matching SegmentAnalytics.
+ *
+ * Task 1 verified: `AnalyticsBrowser.load(settings, options)` returns an
+ * `AnalyticsBrowser` instance **synchronously**. The instance buffers
+ * method calls until the internal load promise resolves.
+ */
+interface SegmentSDK {
+    load: (settings: AnalyticsBrowserSettings, options?: InitOptions) => SegmentAnalytics;
+}
+/**
+ * Env — optional SDK override. Production leaves this undefined and the
+ * destination falls back to the real @segment/analytics-next module.
+ * Tests provide a mock via env.analytics = { ... }.
+ */
+interface Env extends DestinationWeb.Env {
+    analytics?: SegmentSDK;
+}
+
+declare const init: Env | undefined;
+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 merges this on top of a base { apiKey: 'test-project' }.
+ */
+type SegmentStepExample = Flow.StepExample & {
+    settings?: Partial<Settings>;
+    configInclude?: string[];
+};
+/**
+ * Default event forwarding — every walkerOS event becomes
+ * analytics.track(event.name, properties). With no mapping and no
+ * destination-level include, properties is `{}`.
+ */
+declare const defaultEventForwarding: SegmentStepExample;
+/**
+ * Wildcard ignore — walkerOS's standard way to drop events. The rule
+ * matches but does nothing. The destination fires zero SDK calls.
+ */
+declare const wildcardIgnored: SegmentStepExample;
+/**
+ * Destination-level settings.include flattens the walkerOS `data` section
+ * into prefixed properties on every push.
+ */
+declare const destinationLevelInclude: SegmentStepExample;
+/**
+ * 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: SegmentStepExample;
+/**
+ * Destination-level settings.identify fires on the first push. The
+ * destination resolves the mapping, calls analytics.identify(userId),
+ * and records the value in runtime state. Subsequent pushes with the
+ * same userId do NOT re-fire identify().
+ */
+declare const destinationLevelIdentify: SegmentStepExample;
+/**
+ * Per-event identify with traits — the canonical "user login" pattern.
+ * skip: true suppresses the default analytics.track() call because we're
+ * running identity side effects only. Matches Segment Spec reserved traits
+ * (email, name, plan, company) so downstream destinations recognize them.
+ */
+declare const userLoginIdentify: SegmentStepExample;
+/**
+ * Profile update — omit userId. Segment's SDK uses the currently stored
+ * userId and merges the traits into the existing trait set.
+ */
+declare const profileUpdateTraitsOnly: SegmentStepExample;
+/**
+ * User logout — reset: true fires analytics.reset(), which clears userId,
+ * anonymousId, traits, and generates a new anonymous ID.
+ * skip: true because we're only running the reset side effect.
+ */
+declare const userLogoutReset: SegmentStepExample;
+/**
+ * Per-event group assignment — company update event attaches the user
+ * to a company and sets the company's traits in one call.
+ */
+declare const companyUpdateGroup: SegmentStepExample;
+/**
+ * Explicit page() call — the canonical Segment pattern for page views.
+ * skip: true suppresses the default track() call; settings.page fires
+ * analytics.page(category, name, properties) instead.
+ */
+declare const pageViewAsPage: SegmentStepExample;
+/**
+ * Minimal page() call — settings.page: true produces an empty
+ * analytics.page() relying entirely on SDK auto-collection.
+ */
+declare const pageViewMinimal: SegmentStepExample;
+/**
+ * Segment ecommerce spec — Order Completed event. One track() call with
+ * a products array. Uses mapping.name to produce the Segment Spec name
+ * and mapping.data to build the properties object including the nested
+ * products loop. The loop filters via condition to products with prices.
+ */
+declare const orderCompletedEcommerce: SegmentStepExample;
+/**
+ * Consent context forwarding — when the event has consent state,
+ * the destination automatically stamps every track/identify/group/page
+ * call with context.consent.categoryPreferences. settings.consent
+ * remaps walkerOS keys to Segment category names.
+ */
+declare const consentContextForwarded: SegmentStepExample;
+/**
+ * Consent granted → deferred load fires for the first time. The
+ * destination was initialized with consent requirement; on the walker
+ * consent command it calls analytics.load(writeKey, initOptions).
+ *
+ * Uses the canonical StepExample.command='consent' pattern. The full
+ * call shape includes both the settings arg and the initOptions arg.
+ */
+declare const consentGrantDeferredLoad: SegmentStepExample;
+/**
+ * Consent revoked → no SDK call. The walkerOS consent gate handles
+ * blocking subsequent events. The destination's on('consent') handler
+ * is a no-op on revocation (Segment has no opt-out method).
+ */
+declare const consentRevokeNoOp: SegmentStepExample;
+
+type step_SegmentStepExample = SegmentStepExample;
+declare const step_companyUpdateGroup: typeof companyUpdateGroup;
+declare const step_consentContextForwarded: typeof consentContextForwarded;
+declare const step_consentGrantDeferredLoad: typeof consentGrantDeferredLoad;
+declare const step_consentRevokeNoOp: typeof consentRevokeNoOp;
+declare const step_defaultEventForwarding: typeof defaultEventForwarding;
+declare const step_destinationLevelIdentify: typeof destinationLevelIdentify;
+declare const step_destinationLevelInclude: typeof destinationLevelInclude;
+declare const step_orderCompletedEcommerce: typeof orderCompletedEcommerce;
+declare const step_pageViewAsPage: typeof pageViewAsPage;
+declare const step_pageViewMinimal: typeof pageViewMinimal;
+declare const step_profileUpdateTraitsOnly: typeof profileUpdateTraitsOnly;
+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_SegmentStepExample as SegmentStepExample, step_companyUpdateGroup as companyUpdateGroup, step_consentContextForwarded as consentContextForwarded, step_consentGrantDeferredLoad as consentGrantDeferredLoad, step_consentRevokeNoOp as consentRevokeNoOp, step_defaultEventForwarding as defaultEventForwarding, step_destinationLevelIdentify as destinationLevelIdentify, step_destinationLevelInclude as destinationLevelInclude, step_orderCompletedEcommerce as orderCompletedEcommerce, step_pageViewAsPage as pageViewAsPage, step_pageViewMinimal as pageViewMinimal, step_profileUpdateTraitsOnly as profileUpdateTraitsOnly, step_ruleIncludeReplaces as ruleIncludeReplaces, step_userLoginIdentify as userLoginIdentify, step_userLogoutReset as userLogoutReset, step_wildcardIgnored as wildcardIgnored };
+}
+
+export { env, step };