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

package/dist/index.d.mts

@@ -0,0 +1,141 @@
+import { Destination as Destination$1, Mapping as Mapping$1 } from '@walkeros/core';
+import { DestinationWeb } from '@walkeros/web-core';
+import { InitOptions, AnalyticsBrowserSettings } 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$1.Value;
+    /** walkerOS mapping value resolving to a group object (groupId, traits). */
+    group?: Mapping$1.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;
+}
+type InitSettings = Partial<Settings>;
+/**
+ * Per-rule mapping settings. Every feature here is a walkerOS mapping
+ * value resolved via getMappingValue(). The resolved object's keys drive
+ * which Segment SDK methods to call.
+ */
+interface Mapping {
+    identify?: Mapping$1.Value;
+    group?: Mapping$1.Value;
+    page?: Mapping$1.Value | boolean;
+    reset?: Mapping$1.Value | 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;
+}
+type Types = Destination$1.Types<Settings, Mapping, Env, InitSettings>;
+type Destination = DestinationWeb.Destination<Types>;
+type Config = DestinationWeb.Config<Types>;
+interface SegmentDestination extends Destination {
+    env?: Env;
+}
+type Rule = Mapping$1.Rule<Mapping>;
+type Rules = Mapping$1.Rules<Rule>;
+
+type index_Config = Config;
+type index_Destination = Destination;
+type index_Env = Env;
+type index_InitSettings = InitSettings;
+type index_Mapping = Mapping;
+type index_Rule = Rule;
+type index_Rules = Rules;
+type index_RuntimeState = RuntimeState;
+type index_SegmentAnalytics = SegmentAnalytics;
+type index_SegmentDestination = SegmentDestination;
+type index_SegmentEventOptions = SegmentEventOptions;
+type index_SegmentSDK = SegmentSDK;
+type index_Settings = Settings;
+type index_Types = Types;
+declare namespace index {
+  export type { index_Config as Config, index_Destination as Destination, index_Env as Env, index_InitSettings as InitSettings, index_Mapping as Mapping, index_Rule as Rule, index_Rules as Rules, index_RuntimeState as RuntimeState, index_SegmentAnalytics as SegmentAnalytics, index_SegmentDestination as SegmentDestination, index_SegmentEventOptions as SegmentEventOptions, index_SegmentSDK as SegmentSDK, index_Settings as Settings, index_Types as Types };
+}
+
+declare const destinationSegment: Destination;
+
+export { index as DestinationSegment, destinationSegment as default, destinationSegment };

package/dist/index.d.ts

@@ -0,0 +1,141 @@
+import { Destination as Destination$1, Mapping as Mapping$1 } from '@walkeros/core';
+import { DestinationWeb } from '@walkeros/web-core';
+import { InitOptions, AnalyticsBrowserSettings } 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$1.Value;
+    /** walkerOS mapping value resolving to a group object (groupId, traits). */
+    group?: Mapping$1.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;
+}
+type InitSettings = Partial<Settings>;
+/**
+ * Per-rule mapping settings. Every feature here is a walkerOS mapping
+ * value resolved via getMappingValue(). The resolved object's keys drive
+ * which Segment SDK methods to call.
+ */
+interface Mapping {
+    identify?: Mapping$1.Value;
+    group?: Mapping$1.Value;
+    page?: Mapping$1.Value | boolean;
+    reset?: Mapping$1.Value | 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;
+}
+type Types = Destination$1.Types<Settings, Mapping, Env, InitSettings>;
+type Destination = DestinationWeb.Destination<Types>;
+type Config = DestinationWeb.Config<Types>;
+interface SegmentDestination extends Destination {
+    env?: Env;
+}
+type Rule = Mapping$1.Rule<Mapping>;
+type Rules = Mapping$1.Rules<Rule>;
+
+type index_Config = Config;
+type index_Destination = Destination;
+type index_Env = Env;
+type index_InitSettings = InitSettings;
+type index_Mapping = Mapping;
+type index_Rule = Rule;
+type index_Rules = Rules;
+type index_RuntimeState = RuntimeState;
+type index_SegmentAnalytics = SegmentAnalytics;
+type index_SegmentDestination = SegmentDestination;
+type index_SegmentEventOptions = SegmentEventOptions;
+type index_SegmentSDK = SegmentSDK;
+type index_Settings = Settings;
+type index_Types = Types;
+declare namespace index {
+  export type { index_Config as Config, index_Destination as Destination, index_Env as Env, index_InitSettings as InitSettings, index_Mapping as Mapping, index_Rule as Rule, index_Rules as Rules, index_RuntimeState as RuntimeState, index_SegmentAnalytics as SegmentAnalytics, index_SegmentDestination as SegmentDestination, index_SegmentEventOptions as SegmentEventOptions, index_SegmentSDK as SegmentSDK, index_Settings as Settings, index_Types as Types };
+}
+
+declare const destinationSegment: Destination;
+
+export { index as DestinationSegment, destinationSegment as default, destinationSegment };