@walkeros/server-destination-rudderstack 3.4.0-next-1776749829492

package/dist/examples/index.d.mts

@@ -0,0 +1,162 @@
+import { Mapping, Flow } from '@walkeros/core';
+import { DestinationServer } from '@walkeros/server-core';
+
+interface Settings {
+    /** RudderStack source write key (required). */
+    writeKey: string;
+    /** RudderStack data plane URL (required). */
+    dataPlaneUrl: 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;
+    /** Downstream destination filtering. Passthrough to SDK integrations param. */
+    integrations?: Record<string, boolean | Record<string, unknown>>;
+    /** API path. Default: '/v1/batch'. */
+    path?: string;
+    /** Events to enqueue before flushing. Default: 20. */
+    flushAt?: number;
+    /** Max milliseconds before auto-flush. Default: 10000. */
+    flushInterval?: number;
+    /** Maximum batch payload size in bytes. Default: 460800 (~500KB). */
+    maxQueueSize?: number;
+    /** Maximum in-memory queue length. Default: 20000. */
+    maxInternalQueueSize?: number;
+    /** Log level. Default: 'info'. */
+    logLevel?: string;
+    /** Retry attempts for failed batches. Default: 3. */
+    retryCount?: number;
+    /** Completely disable the SDK. Default: false. */
+    enable?: boolean;
+    /** Enable gzip compression. Default: true. */
+    gzip?: boolean;
+    /** Runtime state -- not user-facing. Mutated by init/push. */
+    _analytics?: unknown;
+    _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?: RudderStackAnalyticsMock;
+}
+/**
+ * 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 RudderStackAnalyticsMock {
+    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;
+    alias: (params: Record<string, unknown>) => void;
+    flush: (callback?: (err?: Error, data?: unknown) => void) => 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 RudderStackStepExample = Flow.StepExample & {
+    settings?: Partial<Settings>;
+};
+/**
+ * RudderStack server destination invokes the injected `env.analytics` SDK
+ * methods (`track`, `identify`, `group`, `page`, `screen`, `alias`) — not a
+ * raw HTTP endpoint. Each `out` entry is therefore
+ * `[callable, params]` where `callable` is the dotted method name
+ * (e.g. `'analytics.track'`) and `params` is the object passed to the SDK.
+ *
+ * Examples may emit multiple calls in order (e.g. identify + track), so
+ * every `out` is wrapped as `[[callable, params], ...]`.
+ */
+/**
+ * Default event forwarding -- analytics.track() with event name and empty
+ * properties. userId resolved from default settings.userId = 'user.id'.
+ */
+declare const defaultTrack: RudderStackStepExample;
+/**
+ * Mapped event name -- mapping.name renames the event for RudderStack.
+ */
+declare const mappedEventName: RudderStackStepExample;
+/**
+ * Destination-level identify -- fires analytics.identify() on first push
+ * when settings.identify mapping resolves. Then fires analytics.track().
+ */
+declare const destinationIdentify: RudderStackStepExample;
+/**
+ * Per-event identify with skip -- user login fires identify() only.
+ */
+declare const userLoginIdentify: RudderStackStepExample;
+/**
+ * Per-event group with skip -- company update fires group() only.
+ */
+declare const companyGroup: RudderStackStepExample;
+/**
+ * Explicit page() call with properties. RudderStack requires name -- resolved
+ * from mapping. skip: true suppresses track().
+ */
+declare const pageView: RudderStackStepExample;
+/**
+ * Screen call -- server-only method for mobile app backends.
+ * RudderStack requires name -- resolved from mapping.
+ */
+declare const screenView: RudderStackStepExample;
+/**
+ * Alias call -- links anonymous user identity to registered user.
+ * skip: true suppresses track(). Requires previousId from mapping.
+ */
+declare const aliasUser: RudderStackStepExample;
+/**
+ * AnonymousId only -- no userId resolved. RudderStack accepts anonymousId alone.
+ */
+declare const anonymousOnly: RudderStackStepExample;
+/**
+ * Wildcard ignore -- the event matches a mapping rule with ignore: true.
+ * The destination fires zero SDK calls.
+ */
+declare const wildcardIgnored: RudderStackStepExample;
+
+type step_RudderStackStepExample = RudderStackStepExample;
+declare const step_aliasUser: typeof aliasUser;
+declare const step_anonymousOnly: typeof anonymousOnly;
+declare const step_companyGroup: typeof companyGroup;
+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_RudderStackStepExample as RudderStackStepExample, step_aliasUser as aliasUser, step_anonymousOnly as anonymousOnly, step_companyGroup as companyGroup, 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,162 @@
+import { Mapping, Flow } from '@walkeros/core';
+import { DestinationServer } from '@walkeros/server-core';
+
+interface Settings {
+    /** RudderStack source write key (required). */
+    writeKey: string;
+    /** RudderStack data plane URL (required). */
+    dataPlaneUrl: 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;
+    /** Downstream destination filtering. Passthrough to SDK integrations param. */
+    integrations?: Record<string, boolean | Record<string, unknown>>;
+    /** API path. Default: '/v1/batch'. */
+    path?: string;
+    /** Events to enqueue before flushing. Default: 20. */
+    flushAt?: number;
+    /** Max milliseconds before auto-flush. Default: 10000. */
+    flushInterval?: number;
+    /** Maximum batch payload size in bytes. Default: 460800 (~500KB). */
+    maxQueueSize?: number;
+    /** Maximum in-memory queue length. Default: 20000. */
+    maxInternalQueueSize?: number;
+    /** Log level. Default: 'info'. */
+    logLevel?: string;
+    /** Retry attempts for failed batches. Default: 3. */
+    retryCount?: number;
+    /** Completely disable the SDK. Default: false. */
+    enable?: boolean;
+    /** Enable gzip compression. Default: true. */
+    gzip?: boolean;
+    /** Runtime state -- not user-facing. Mutated by init/push. */
+    _analytics?: unknown;
+    _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?: RudderStackAnalyticsMock;
+}
+/**
+ * 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 RudderStackAnalyticsMock {
+    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;
+    alias: (params: Record<string, unknown>) => void;
+    flush: (callback?: (err?: Error, data?: unknown) => void) => 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 RudderStackStepExample = Flow.StepExample & {
+    settings?: Partial<Settings>;
+};
+/**
+ * RudderStack server destination invokes the injected `env.analytics` SDK
+ * methods (`track`, `identify`, `group`, `page`, `screen`, `alias`) — not a
+ * raw HTTP endpoint. Each `out` entry is therefore
+ * `[callable, params]` where `callable` is the dotted method name
+ * (e.g. `'analytics.track'`) and `params` is the object passed to the SDK.
+ *
+ * Examples may emit multiple calls in order (e.g. identify + track), so
+ * every `out` is wrapped as `[[callable, params], ...]`.
+ */
+/**
+ * Default event forwarding -- analytics.track() with event name and empty
+ * properties. userId resolved from default settings.userId = 'user.id'.
+ */
+declare const defaultTrack: RudderStackStepExample;
+/**
+ * Mapped event name -- mapping.name renames the event for RudderStack.
+ */
+declare const mappedEventName: RudderStackStepExample;
+/**
+ * Destination-level identify -- fires analytics.identify() on first push
+ * when settings.identify mapping resolves. Then fires analytics.track().
+ */
+declare const destinationIdentify: RudderStackStepExample;
+/**
+ * Per-event identify with skip -- user login fires identify() only.
+ */
+declare const userLoginIdentify: RudderStackStepExample;
+/**
+ * Per-event group with skip -- company update fires group() only.
+ */
+declare const companyGroup: RudderStackStepExample;
+/**
+ * Explicit page() call with properties. RudderStack requires name -- resolved
+ * from mapping. skip: true suppresses track().
+ */
+declare const pageView: RudderStackStepExample;
+/**
+ * Screen call -- server-only method for mobile app backends.
+ * RudderStack requires name -- resolved from mapping.
+ */
+declare const screenView: RudderStackStepExample;
+/**
+ * Alias call -- links anonymous user identity to registered user.
+ * skip: true suppresses track(). Requires previousId from mapping.
+ */
+declare const aliasUser: RudderStackStepExample;
+/**
+ * AnonymousId only -- no userId resolved. RudderStack accepts anonymousId alone.
+ */
+declare const anonymousOnly: RudderStackStepExample;
+/**
+ * Wildcard ignore -- the event matches a mapping rule with ignore: true.
+ * The destination fires zero SDK calls.
+ */
+declare const wildcardIgnored: RudderStackStepExample;
+
+type step_RudderStackStepExample = RudderStackStepExample;
+declare const step_aliasUser: typeof aliasUser;
+declare const step_anonymousOnly: typeof anonymousOnly;
+declare const step_companyGroup: typeof companyGroup;
+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_RudderStackStepExample as RudderStackStepExample, step_aliasUser as aliasUser, step_anonymousOnly as anonymousOnly, step_companyGroup as companyGroup, 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,369 @@
+"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,
+    alias: noop,
+    flush: asyncNoop
+  };
+}
+var push = {
+  analytics: createMockAnalytics()
+};
+var simulation = [
+  "call:analytics.track",
+  "call:analytics.identify",
+  "call:analytics.group",
+  "call:analytics.page",
+  "call:analytics.screen",
+  "call:analytics.alias"
+];
+
+// src/examples/step.ts
+var step_exports = {};
+__export(step_exports, {
+  aliasUser: () => aliasUser,
+  anonymousOnly: () => anonymousOnly,
+  companyGroup: () => companyGroup,
+  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: {
+      title: "Getting Started",
+      section: "tutorials"
+    }
+  }),
+  mapping: {
+    skip: true,
+    settings: {
+      page: {
+        map: {
+          name: "data.title",
+          properties: {
+            map: {
+              section: "data.section"
+            }
+          }
+        }
+      }
+    }
+  },
+  out: [
+    [
+      "analytics.page",
+      {
+        userId: "us3r",
+        anonymousId: "s3ss10n",
+        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",
+          properties: {
+            map: {
+              build: "data.build"
+            }
+          }
+        }
+      }
+    }
+  },
+  out: [
+    [
+      "analytics.screen",
+      {
+        userId: "us3r",
+        anonymousId: "s3ss10n",
+        name: "Welcome",
+        properties: { build: "1.2.3" },
+        timestamp: /* @__PURE__ */ new Date(1700000106)
+      }
+    ]
+  ]
+};
+var aliasUser = {
+  in: (0, import_core.getEvent)("identity merge", {
+    timestamp: 1700000107,
+    user: { id: "registered-456", session: "s3ss10n" },
+    data: {
+      anonymous_id: "anonymous-123"
+    }
+  }),
+  mapping: {
+    skip: true,
+    settings: {
+      alias: {
+        map: {
+          previousId: "data.anonymous_id"
+        }
+      }
+    }
+  },
+  out: [
+    [
+      "analytics.alias",
+      {
+        userId: "registered-456",
+        previousId: "anonymous-123",
+        timestamp: /* @__PURE__ */ new Date(1700000107)
+      }
+    ]
+  ]
+};
+var anonymousOnly = {
+  in: (0, import_core.getEvent)("product view", {
+    timestamp: 1700000108,
+    user: { session: "s3ss10n" }
+  }),
+  settings: {
+    userId: void 0
+  },
+  out: [
+    [
+      "analytics.track",
+      {
+        anonymousId: "s3ss10n",
+        event: "product view",
+        properties: {},
+        timestamp: /* @__PURE__ */ new Date(1700000108)
+      }
+    ]
+  ]
+};
+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
+});