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

package/dist/examples/index.d.mts

@@ -0,0 +1,149 @@
+import { Mapping, Flow } from '@walkeros/core';
+import { DestinationServer } from '@walkeros/server-core';
+import { Analytics } from '@segment/analytics-node';
+
+interface Settings {
+    /** Segment source write key (required). */
+    writeKey: string;
+    /** walkerOS mapping value path to resolve userId from each event. */
+    userId?: string;
+    /** walkerOS mapping value path to resolve anonymousId from each event. */
+    anonymousId?: string;
+    /** Destination-level identity mapping (fires identify() on first push / change). */
+    identify?: Mapping.Value;
+    /** Destination-level group mapping (fires group() on first push / change). */
+    group?: Mapping.Value;
+    /** walkerOS consent key -> Segment categoryPreferences key mapping. */
+    consent?: Record<string, string>;
+    /** Downstream destination filtering. Passthrough to SDK. */
+    integrations?: Record<string, boolean | Record<string, unknown>>;
+    /** Base URL of Segment API. Default: 'https://api.segment.io'. */
+    host?: string;
+    /** API path. Default: '/v1/batch'. */
+    path?: string;
+    /** Events to enqueue before flushing. Default: 15. */
+    flushAt?: number;
+    /** Max milliseconds before auto-flush. Default: 10000. */
+    flushInterval?: number;
+    /** Retry attempts for failed batches. Default: 3. */
+    maxRetries?: number;
+    /** HTTP request timeout (ms). Default: 10000. */
+    httpRequestTimeout?: number;
+    /** Completely disable the SDK. Default: false. */
+    disable?: boolean;
+    /** Runtime state -- not user-facing. Mutated by init/push. */
+    _analytics?: Analytics;
+    _state?: RuntimeState;
+}
+interface RuntimeState {
+    lastIdentity?: {
+        userId?: string;
+        anonymousId?: string;
+        traitsHash?: string;
+    };
+    lastGroup?: {
+        groupId?: string;
+        traitsHash?: string;
+    };
+}
+/**
+ * Env -- optional SDK override. Production leaves this undefined and the
+ * destination creates a real Analytics instance. Tests provide a mock via
+ * env.analytics.
+ */
+interface Env extends DestinationServer.Env {
+    analytics?: SegmentAnalyticsMock;
+}
+/**
+ * Mock-friendly interface for the Analytics instance methods the
+ * destination actually calls. Tests can provide this via env.analytics
+ * instead of the real SDK.
+ */
+interface SegmentAnalyticsMock {
+    track: (params: Record<string, unknown>) => void;
+    identify: (params: Record<string, unknown>) => void;
+    group: (params: Record<string, unknown>) => void;
+    page: (params: Record<string, unknown>) => void;
+    screen: (params: Record<string, unknown>) => void;
+    closeAndFlush: (opts?: {
+        timeout?: number;
+    }) => Promise<void>;
+}
+
+declare const push: Env;
+declare const simulation: string[];
+
+declare const env_push: typeof push;
+declare const env_simulation: typeof simulation;
+declare namespace env {
+  export { env_push as push, env_simulation as simulation };
+}
+
+/**
+ * Extended step example that may carry destination-level settings overrides.
+ */
+type SegmentStepExample = Flow.StepExample & {
+    settings?: Partial<Settings>;
+};
+/**
+ * Default event forwarding -- analytics.track() with event name and empty
+ * properties. userId resolved from default settings.userId = 'user.id'.
+ */
+declare const defaultTrack: SegmentStepExample;
+/**
+ * Mapped event name -- mapping.name renames the event for Segment.
+ */
+declare const mappedEventName: SegmentStepExample;
+/**
+ * Destination-level identify -- fires analytics.identify() on first push
+ * when settings.identify mapping resolves. Then fires analytics.track().
+ */
+declare const destinationIdentify: SegmentStepExample;
+/**
+ * Per-event identify with skip -- user login fires identify() only.
+ */
+declare const userLoginIdentify: SegmentStepExample;
+/**
+ * Per-event group with skip -- company update fires group() only.
+ */
+declare const companyGroup: SegmentStepExample;
+/**
+ * Explicit page() call with properties -- the canonical Segment page view.
+ * skip: true suppresses track(); settings.page fires analytics.page().
+ */
+declare const pageView: SegmentStepExample;
+/**
+ * Screen call -- server-only method for mobile app backends.
+ */
+declare const screenView: SegmentStepExample;
+/**
+ * AnonymousId only -- no userId resolved. Segment accepts anonymousId alone.
+ */
+declare const anonymousOnly: SegmentStepExample;
+/**
+ * Consent context forwarding -- settings.consent maps walkerOS consent
+ * keys to Segment categoryPreferences on the context object.
+ */
+declare const consentForwarding: SegmentStepExample;
+/**
+ * Wildcard ignore -- the event matches a mapping rule with ignore: true.
+ * The destination fires zero SDK calls.
+ */
+declare const wildcardIgnored: SegmentStepExample;
+
+type step_SegmentStepExample = SegmentStepExample;
+declare const step_anonymousOnly: typeof anonymousOnly;
+declare const step_companyGroup: typeof companyGroup;
+declare const step_consentForwarding: typeof consentForwarding;
+declare const step_defaultTrack: typeof defaultTrack;
+declare const step_destinationIdentify: typeof destinationIdentify;
+declare const step_mappedEventName: typeof mappedEventName;
+declare const step_pageView: typeof pageView;
+declare const step_screenView: typeof screenView;
+declare const step_userLoginIdentify: typeof userLoginIdentify;
+declare const step_wildcardIgnored: typeof wildcardIgnored;
+declare namespace step {
+  export { type step_SegmentStepExample as SegmentStepExample, step_anonymousOnly as anonymousOnly, step_companyGroup as companyGroup, step_consentForwarding as consentForwarding, step_defaultTrack as defaultTrack, step_destinationIdentify as destinationIdentify, step_mappedEventName as mappedEventName, step_pageView as pageView, step_screenView as screenView, step_userLoginIdentify as userLoginIdentify, step_wildcardIgnored as wildcardIgnored };
+}
+
+export { env, step };

package/dist/examples/index.d.ts

@@ -0,0 +1,149 @@
+import { Mapping, Flow } from '@walkeros/core';
+import { DestinationServer } from '@walkeros/server-core';
+import { Analytics } from '@segment/analytics-node';
+
+interface Settings {
+    /** Segment source write key (required). */
+    writeKey: string;
+    /** walkerOS mapping value path to resolve userId from each event. */
+    userId?: string;
+    /** walkerOS mapping value path to resolve anonymousId from each event. */
+    anonymousId?: string;
+    /** Destination-level identity mapping (fires identify() on first push / change). */
+    identify?: Mapping.Value;
+    /** Destination-level group mapping (fires group() on first push / change). */
+    group?: Mapping.Value;
+    /** walkerOS consent key -> Segment categoryPreferences key mapping. */
+    consent?: Record<string, string>;
+    /** Downstream destination filtering. Passthrough to SDK. */
+    integrations?: Record<string, boolean | Record<string, unknown>>;
+    /** Base URL of Segment API. Default: 'https://api.segment.io'. */
+    host?: string;
+    /** API path. Default: '/v1/batch'. */
+    path?: string;
+    /** Events to enqueue before flushing. Default: 15. */
+    flushAt?: number;
+    /** Max milliseconds before auto-flush. Default: 10000. */
+    flushInterval?: number;
+    /** Retry attempts for failed batches. Default: 3. */
+    maxRetries?: number;
+    /** HTTP request timeout (ms). Default: 10000. */
+    httpRequestTimeout?: number;
+    /** Completely disable the SDK. Default: false. */
+    disable?: boolean;
+    /** Runtime state -- not user-facing. Mutated by init/push. */
+    _analytics?: Analytics;
+    _state?: RuntimeState;
+}
+interface RuntimeState {
+    lastIdentity?: {
+        userId?: string;
+        anonymousId?: string;
+        traitsHash?: string;
+    };
+    lastGroup?: {
+        groupId?: string;
+        traitsHash?: string;
+    };
+}
+/**
+ * Env -- optional SDK override. Production leaves this undefined and the
+ * destination creates a real Analytics instance. Tests provide a mock via
+ * env.analytics.
+ */
+interface Env extends DestinationServer.Env {
+    analytics?: SegmentAnalyticsMock;
+}
+/**
+ * Mock-friendly interface for the Analytics instance methods the
+ * destination actually calls. Tests can provide this via env.analytics
+ * instead of the real SDK.
+ */
+interface SegmentAnalyticsMock {
+    track: (params: Record<string, unknown>) => void;
+    identify: (params: Record<string, unknown>) => void;
+    group: (params: Record<string, unknown>) => void;
+    page: (params: Record<string, unknown>) => void;
+    screen: (params: Record<string, unknown>) => void;
+    closeAndFlush: (opts?: {
+        timeout?: number;
+    }) => Promise<void>;
+}
+
+declare const push: Env;
+declare const simulation: string[];
+
+declare const env_push: typeof push;
+declare const env_simulation: typeof simulation;
+declare namespace env {
+  export { env_push as push, env_simulation as simulation };
+}
+
+/**
+ * Extended step example that may carry destination-level settings overrides.
+ */
+type SegmentStepExample = Flow.StepExample & {
+    settings?: Partial<Settings>;
+};
+/**
+ * Default event forwarding -- analytics.track() with event name and empty
+ * properties. userId resolved from default settings.userId = 'user.id'.
+ */
+declare const defaultTrack: SegmentStepExample;
+/**
+ * Mapped event name -- mapping.name renames the event for Segment.
+ */
+declare const mappedEventName: SegmentStepExample;
+/**
+ * Destination-level identify -- fires analytics.identify() on first push
+ * when settings.identify mapping resolves. Then fires analytics.track().
+ */
+declare const destinationIdentify: SegmentStepExample;
+/**
+ * Per-event identify with skip -- user login fires identify() only.
+ */
+declare const userLoginIdentify: SegmentStepExample;
+/**
+ * Per-event group with skip -- company update fires group() only.
+ */
+declare const companyGroup: SegmentStepExample;
+/**
+ * Explicit page() call with properties -- the canonical Segment page view.
+ * skip: true suppresses track(); settings.page fires analytics.page().
+ */
+declare const pageView: SegmentStepExample;
+/**
+ * Screen call -- server-only method for mobile app backends.
+ */
+declare const screenView: SegmentStepExample;
+/**
+ * AnonymousId only -- no userId resolved. Segment accepts anonymousId alone.
+ */
+declare const anonymousOnly: SegmentStepExample;
+/**
+ * Consent context forwarding -- settings.consent maps walkerOS consent
+ * keys to Segment categoryPreferences on the context object.
+ */
+declare const consentForwarding: SegmentStepExample;
+/**
+ * Wildcard ignore -- the event matches a mapping rule with ignore: true.
+ * The destination fires zero SDK calls.
+ */
+declare const wildcardIgnored: SegmentStepExample;
+
+type step_SegmentStepExample = SegmentStepExample;
+declare const step_anonymousOnly: typeof anonymousOnly;
+declare const step_companyGroup: typeof companyGroup;
+declare const step_consentForwarding: typeof consentForwarding;
+declare const step_defaultTrack: typeof defaultTrack;
+declare const step_destinationIdentify: typeof destinationIdentify;
+declare const step_mappedEventName: typeof mappedEventName;
+declare const step_pageView: typeof pageView;
+declare const step_screenView: typeof screenView;
+declare const step_userLoginIdentify: typeof userLoginIdentify;
+declare const step_wildcardIgnored: typeof wildcardIgnored;
+declare namespace step {
+  export { type step_SegmentStepExample as SegmentStepExample, step_anonymousOnly as anonymousOnly, step_companyGroup as companyGroup, step_consentForwarding as consentForwarding, step_defaultTrack as defaultTrack, step_destinationIdentify as destinationIdentify, step_mappedEventName as mappedEventName, step_pageView as pageView, step_screenView as screenView, step_userLoginIdentify as userLoginIdentify, step_wildcardIgnored as wildcardIgnored };
+}
+
+export { env, step };

package/dist/examples/index.js

@@ -0,0 +1,360 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/examples/index.ts
+var examples_exports = {};
+__export(examples_exports, {
+  env: () => env_exports,
+  step: () => step_exports
+});
+module.exports = __toCommonJS(examples_exports);
+
+// src/examples/env.ts
+var env_exports = {};
+__export(env_exports, {
+  push: () => push,
+  simulation: () => simulation
+});
+var noop = () => {
+};
+var asyncNoop = () => Promise.resolve();
+function createMockAnalytics() {
+  return {
+    track: noop,
+    identify: noop,
+    group: noop,
+    page: noop,
+    screen: noop,
+    closeAndFlush: asyncNoop
+  };
+}
+var push = {
+  analytics: createMockAnalytics()
+};
+var simulation = [
+  "call:analytics.track",
+  "call:analytics.identify",
+  "call:analytics.group",
+  "call:analytics.page",
+  "call:analytics.screen"
+];
+
+// src/examples/step.ts
+var step_exports = {};
+__export(step_exports, {
+  anonymousOnly: () => anonymousOnly,
+  companyGroup: () => companyGroup,
+  consentForwarding: () => consentForwarding,
+  defaultTrack: () => defaultTrack,
+  destinationIdentify: () => destinationIdentify,
+  mappedEventName: () => mappedEventName,
+  pageView: () => pageView,
+  screenView: () => screenView,
+  userLoginIdentify: () => userLoginIdentify,
+  wildcardIgnored: () => wildcardIgnored
+});
+var import_core = require("@walkeros/core");
+var defaultTrack = {
+  in: (0, import_core.getEvent)("product view", {
+    timestamp: 1700000100,
+    user: { id: "us3r", session: "s3ss10n" }
+  }),
+  out: [
+    "analytics.track",
+    {
+      userId: "us3r",
+      anonymousId: "s3ss10n",
+      event: "product view",
+      properties: {},
+      timestamp: /* @__PURE__ */ new Date(1700000100)
+    }
+  ]
+};
+var mappedEventName = {
+  in: (0, import_core.getEvent)("order complete", {
+    timestamp: 1700000101,
+    user: { id: "us3r", session: "s3ss10n" }
+  }),
+  mapping: {
+    name: "Order Completed"
+  },
+  out: [
+    "analytics.track",
+    {
+      userId: "us3r",
+      anonymousId: "s3ss10n",
+      event: "Order Completed",
+      properties: {},
+      timestamp: /* @__PURE__ */ new Date(1700000101)
+    }
+  ]
+};
+var destinationIdentify = {
+  in: (0, import_core.getEvent)("page view", {
+    timestamp: 1700000102,
+    user: { id: "us3r", session: "s3ss10n", email: "user@example.com" }
+  }),
+  settings: {
+    identify: {
+      map: {
+        traits: {
+          map: {
+            email: "user.email"
+          }
+        }
+      }
+    }
+  },
+  out: [
+    [
+      "analytics.identify",
+      {
+        userId: "us3r",
+        anonymousId: "s3ss10n",
+        traits: { email: "user@example.com" },
+        timestamp: /* @__PURE__ */ new Date(1700000102)
+      }
+    ],
+    [
+      "analytics.track",
+      {
+        userId: "us3r",
+        anonymousId: "s3ss10n",
+        event: "page view",
+        properties: {},
+        timestamp: /* @__PURE__ */ new Date(1700000102)
+      }
+    ]
+  ]
+};
+var userLoginIdentify = {
+  in: (0, import_core.getEvent)("user login", {
+    timestamp: 1700000103,
+    user: { id: "us3r", session: "s3ss10n" },
+    data: {
+      user_id: "new-user-123",
+      email: "user@acme.com",
+      name: "Jane Doe",
+      plan: "premium"
+    }
+  }),
+  mapping: {
+    skip: true,
+    settings: {
+      identify: {
+        map: {
+          userId: "data.user_id",
+          traits: {
+            map: {
+              email: "data.email",
+              name: "data.name",
+              plan: "data.plan"
+            }
+          }
+        }
+      }
+    }
+  },
+  out: [
+    "analytics.identify",
+    {
+      userId: "new-user-123",
+      anonymousId: "s3ss10n",
+      traits: { email: "user@acme.com", name: "Jane Doe", plan: "premium" },
+      timestamp: /* @__PURE__ */ new Date(1700000103)
+    }
+  ]
+};
+var companyGroup = {
+  in: (0, import_core.getEvent)("company update", {
+    timestamp: 1700000104,
+    user: { id: "us3r", session: "s3ss10n" },
+    data: {
+      company_id: "comp-456",
+      company_name: "Acme",
+      industry: "tech",
+      employees: 50
+    }
+  }),
+  mapping: {
+    skip: true,
+    settings: {
+      group: {
+        map: {
+          groupId: "data.company_id",
+          traits: {
+            map: {
+              name: "data.company_name",
+              industry: "data.industry",
+              employees: "data.employees"
+            }
+          }
+        }
+      }
+    }
+  },
+  out: [
+    "analytics.group",
+    {
+      userId: "us3r",
+      anonymousId: "s3ss10n",
+      groupId: "comp-456",
+      traits: { name: "Acme", industry: "tech", employees: 50 },
+      timestamp: /* @__PURE__ */ new Date(1700000104)
+    }
+  ]
+};
+var pageView = {
+  in: (0, import_core.getEvent)("page view", {
+    timestamp: 1700000105,
+    user: { id: "us3r", session: "s3ss10n" },
+    data: {
+      category: "docs",
+      title: "Getting Started",
+      section: "tutorials"
+    }
+  }),
+  mapping: {
+    skip: true,
+    settings: {
+      page: {
+        map: {
+          category: "data.category",
+          name: "data.title",
+          properties: {
+            map: {
+              section: "data.section"
+            }
+          }
+        }
+      }
+    }
+  },
+  out: [
+    "analytics.page",
+    {
+      userId: "us3r",
+      anonymousId: "s3ss10n",
+      category: "docs",
+      name: "Getting Started",
+      properties: { section: "tutorials" },
+      timestamp: /* @__PURE__ */ new Date(1700000105)
+    }
+  ]
+};
+var screenView = {
+  in: (0, import_core.getEvent)("screen view", {
+    timestamp: 1700000106,
+    user: { id: "us3r", session: "s3ss10n" },
+    data: {
+      screen_name: "Welcome",
+      section: "onboarding",
+      build: "1.2.3"
+    }
+  }),
+  mapping: {
+    skip: true,
+    settings: {
+      screen: {
+        map: {
+          name: "data.screen_name",
+          category: "data.section",
+          properties: {
+            map: {
+              build: "data.build"
+            }
+          }
+        }
+      }
+    }
+  },
+  out: [
+    "analytics.screen",
+    {
+      userId: "us3r",
+      anonymousId: "s3ss10n",
+      name: "Welcome",
+      category: "onboarding",
+      properties: { build: "1.2.3" },
+      timestamp: /* @__PURE__ */ new Date(1700000106)
+    }
+  ]
+};
+var anonymousOnly = {
+  in: (0, import_core.getEvent)("product view", {
+    timestamp: 1700000107,
+    user: { session: "s3ss10n" }
+  }),
+  settings: {
+    userId: void 0
+  },
+  out: [
+    "analytics.track",
+    {
+      anonymousId: "s3ss10n",
+      event: "product view",
+      properties: {},
+      timestamp: /* @__PURE__ */ new Date(1700000107)
+    }
+  ]
+};
+var consentForwarding = {
+  in: (0, import_core.getEvent)("product view", {
+    timestamp: 1700000108,
+    user: { id: "us3r", session: "s3ss10n" },
+    consent: { analytics: true, marketing: true }
+  }),
+  settings: {
+    consent: {
+      analytics: "Analytics",
+      marketing: "Advertising"
+    }
+  },
+  out: [
+    "analytics.track",
+    {
+      userId: "us3r",
+      anonymousId: "s3ss10n",
+      event: "product view",
+      properties: {},
+      timestamp: /* @__PURE__ */ new Date(1700000108),
+      context: {
+        consent: {
+          categoryPreferences: {
+            Analytics: true,
+            Advertising: true
+          }
+        }
+      }
+    }
+  ]
+};
+var wildcardIgnored = {
+  in: (0, import_core.getEvent)("debug noise", {
+    timestamp: 1700000109,
+    user: { id: "us3r", session: "s3ss10n" }
+  }),
+  mapping: { ignore: true },
+  out: []
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  env,
+  step
+});