@walkeros/web-destination-optimizely 3.4.0-next-1776749829492

package/README.md

@@ -0,0 +1,121 @@
+# @walkeros/web-destination-optimizely
+
+Optimizely Feature Experimentation web destination for
+[walkerOS](https://github.com/elbwalker/walkerOS). Forwards conversion events to
+Optimizely via the official `@optimizely/optimizely-sdk` v6 modular API with
+support for revenue/value event tags, user targeting attributes, and
+consent-based client lifecycle.
+
+## Installation
+
+```bash
+npm install @walkeros/web-destination-optimizely
+```
+
+## Quick Start
+
+```json
+{
+  "destinations": {
+    "optimizely": {
+      "package": "@walkeros/web-destination-optimizely",
+      "config": {
+        "consent": { "analytics": true },
+        "settings": {
+          "sdkKey": "YOUR_SDK_KEY",
+          "userId": "user.id"
+        }
+      }
+    }
+  }
+}
+```
+
+Programmatic:
+
+```ts
+import { startFlow } from '@walkeros/collector';
+import destinationOptimizely from '@walkeros/web-destination-optimizely';
+
+const { elb } = await startFlow();
+
+elb('walker destination', destinationOptimizely, {
+  consent: { analytics: true },
+  settings: {
+    sdkKey: 'YOUR_SDK_KEY',
+    userId: 'user.id',
+  },
+});
+```
+
+## Settings
+
+| Key              | Type      | Default | Description                                                                                               |
+| ---------------- | --------- | ------- | --------------------------------------------------------------------------------------------------------- |
+| `sdkKey`         | `string`  | —       | Required. Optimizely Feature Experimentation SDK key (Settings > Environments).                           |
+| `userId`         | `Mapping` | —       | walkerOS mapping value resolving to the userId used for bucketing (e.g. `"user.id"`). Required per event. |
+| `attributes`     | `Mapping` | —       | Destination-level user attributes for audience targeting. Applied via `createUserContext()`.              |
+| `updateInterval` | `number`  | `60000` | Datafile polling interval (ms).                                                                           |
+| `autoUpdate`     | `boolean` | `true`  | Poll for datafile updates.                                                                                |
+| `batchSize`      | `number`  | `10`    | Events per batch (batch event processor).                                                                 |
+| `flushInterval`  | `number`  | `1000`  | Batch flush interval (ms).                                                                                |
+| `skipOdp`        | `boolean` | `true`  | Skip Optimizely Data Platform manager init.                                                               |
+
+## Mapping
+
+Per-rule overrides under `mapping.<entity>.<action>.settings`:
+
+| Key          | Type      | Description                                                                             |
+| ------------ | --------- | --------------------------------------------------------------------------------------- |
+| `eventKey`   | `string`  | Override event key sent to Optimizely. If omitted, the walkerOS event name is used.     |
+| `revenue`    | `Mapping` | Resolves to integer cents. Passed as `eventTags.revenue`.                               |
+| `value`      | `Mapping` | Resolves to a float. Passed as `eventTags.value`.                                       |
+| `eventTags`  | `Mapping` | Extra tags. Spread into the `eventTags` object.                                         |
+| `attributes` | `Mapping` | Per-event user attributes. Applied via `setAttribute()` before the `trackEvent()` call. |
+
+Use `rule.name` to rename the event key and `rule.skip = true` to fire
+attributes without a `trackEvent()` call.
+
+## Revenue
+
+Optimizely expects revenue as an **integer in cents** (e.g. `7281` = `$72.81`).
+The destination passes the resolved value through without conversion — you must
+provide cents.
+
+```json
+{
+  "order": {
+    "complete": {
+      "name": "purchase",
+      "settings": {
+        "revenue": "data.revenue_cents",
+        "value": "data.total"
+      }
+    }
+  }
+}
+```
+
+## Consent
+
+Two layers:
+
+1. **`config.consent`** — walkerOS gates delivery. Events are queued until
+   required consent keys resolve to `true`.
+2. **`on('consent')`** — the destination closes the Optimizely client (flushing
+   queued events and stopping polling) when any required key flips to `false`.
+   On re-grant, the next push re-initializes the client.
+
+```json
+"config": { "consent": { "analytics": true } }
+```
+
+## Decide / Feature Flags
+
+This destination intentionally does **not** expose `decide()` — experiment
+decisions belong in application code where UI branching happens. This package
+covers the outbound conversion-tracking use case.
+
+## License
+
+MIT

package/dist/dev.d.mts

@@ -0,0 +1,193 @@
+import * as _walkeros_core_dev from '@walkeros/core/dev';
+import { z } from '@walkeros/core/dev';
+import { Mapping as Mapping$1, Flow } from '@walkeros/core';
+import { DestinationWeb } from '@walkeros/web-core';
+
+declare const SettingsSchema: z.ZodObject<{
+    sdkKey: z.ZodString;
+    userId: z.ZodOptional<z.ZodUnknown>;
+    attributes: z.ZodOptional<z.ZodUnknown>;
+    updateInterval: z.ZodOptional<z.ZodNumber>;
+    autoUpdate: z.ZodOptional<z.ZodBoolean>;
+    batchSize: z.ZodOptional<z.ZodNumber>;
+    flushInterval: z.ZodOptional<z.ZodNumber>;
+    skipOdp: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type Settings$1 = z.infer<typeof SettingsSchema>;
+
+declare const MappingSchema: z.ZodObject<{
+    eventKey: z.ZodOptional<z.ZodString>;
+    revenue: z.ZodOptional<z.ZodUnknown>;
+    value: z.ZodOptional<z.ZodUnknown>;
+    eventTags: z.ZodOptional<z.ZodUnknown>;
+    attributes: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+type Mapping = z.infer<typeof MappingSchema>;
+
+declare const settings: _walkeros_core_dev.JSONSchema;
+declare const mapping: _walkeros_core_dev.JSONSchema;
+
+type index$1_Mapping = Mapping;
+declare const index$1_MappingSchema: typeof MappingSchema;
+declare const index$1_SettingsSchema: typeof SettingsSchema;
+declare const index$1_mapping: typeof mapping;
+declare const index$1_settings: typeof settings;
+declare namespace index$1 {
+  export { type index$1_Mapping as Mapping, index$1_MappingSchema as MappingSchema, type Settings$1 as Settings, index$1_SettingsSchema as SettingsSchema, index$1_mapping as mapping, index$1_settings as settings };
+}
+
+/**
+ * Destination-level settings.
+ */
+interface Settings {
+    /** Optimizely Feature Experimentation SDK key. Required. */
+    sdkKey: string;
+    /** walkerOS mapping value to resolve userId for experiment bucketing. */
+    userId?: Mapping$1.Value;
+    /** User attributes for audience targeting, applied to every event. */
+    attributes?: Mapping$1.Value;
+    /** Polling interval for datafile updates in ms. Default: 60000. */
+    updateInterval?: number;
+    /** Auto-update datafile via polling. Default: true. */
+    autoUpdate?: boolean;
+    /** Batch event processor: events per batch. Default: 10. */
+    batchSize?: number;
+    /** Batch event processor: flush interval in ms. Default: 1000. */
+    flushInterval?: number;
+    /** Skip ODP manager initialization. Default: true. */
+    skipOdp?: boolean;
+    /** Runtime state -- not user-facing. Mutated by init/push. */
+    _state?: RuntimeState;
+}
+interface RuntimeState {
+    /** The Optimizely client instance (typed as OptimizelyClient). */
+    client?: OptimizelyClient;
+    /** Cached user context. Recreated when userId changes. */
+    userContext?: OptimizelyUserContext;
+    /** Last resolved userId to detect identity changes. */
+    lastUserId?: string;
+}
+/**
+ * OptimizelyClient -- the subset of the Optimizely SDK client the destination
+ * actually uses. Tests provide a mock via env.optimizely.
+ */
+interface OptimizelyClient {
+    onReady: () => Promise<{
+        success: boolean;
+    }>;
+    createUserContext: (userId: string, attributes?: Record<string, unknown>) => OptimizelyUserContext | null;
+    close: () => void;
+}
+/**
+ * OptimizelyUserContext -- user context methods the destination calls.
+ */
+interface OptimizelyUserContext {
+    trackEvent: (eventKey: string, eventTags?: Record<string, unknown>) => void;
+    setAttribute: (key: string, value: unknown) => void;
+}
+/**
+ * OptimizelySDK -- factory functions the destination imports from the SDK.
+ * Tests provide this via env.optimizely to avoid importing the real SDK.
+ */
+interface OptimizelySDK {
+    createInstance: (config: Record<string, unknown>) => OptimizelyClient;
+    createPollingProjectConfigManager: (config: Record<string, unknown>) => unknown;
+    createBatchEventProcessor: (config: Record<string, unknown>) => unknown;
+}
+/**
+ * Env -- optional SDK override. Production leaves env.optimizely undefined
+ * and the destination falls back to the real @optimizely/optimizely-sdk
+ * import. Tests provide a mock via env.optimizely.
+ */
+interface Env extends DestinationWeb.Env {
+    optimizely?: OptimizelySDK;
+}
+
+/**
+ * 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 };
+}
+
+/**
+ * Extended step example that may carry destination-level settings overrides.
+ */
+type OptimizelyStepExample = Flow.StepExample & {
+    settings?: Partial<Settings>;
+};
+/**
+ * Default event forwarding -- every walkerOS event becomes
+ * userContext.trackEvent(event.name). No mapping, no eventTags.
+ */
+declare const defaultEventForwarding: OptimizelyStepExample;
+/**
+ * Mapped event name -- mapping.name renames the event key for Optimizely.
+ * The eventKey must match an event created in the Optimizely project.
+ */
+declare const mappedEventName: OptimizelyStepExample;
+/**
+ * Revenue tracking -- mapping.settings.revenue resolves to an integer
+ * (cents). Passed as eventTags.revenue. The value is a pass-through;
+ * the user must provide cents (e.g. 55500 = $555.00).
+ */
+declare const orderCompleteRevenue: OptimizelyStepExample;
+/**
+ * Per-event attributes -- mapping.settings.attributes resolves to
+ * key-value pairs that are applied via setAttribute() before trackEvent().
+ */
+declare const signupWithAttributes: OptimizelyStepExample;
+/**
+ * Wildcard ignore -- walkerOS's standard way to drop events. The rule
+ * matches but does nothing. The destination fires zero SDK calls.
+ */
+declare const wildcardIgnored: OptimizelyStepExample;
+/**
+ * Skip track with attributes only -- fires setAttribute calls but no
+ * trackEvent. Useful for enriching user context without a conversion.
+ */
+declare const attributesOnlySkipTrack: OptimizelyStepExample;
+/**
+ * Consent revoked -- the destination closes the Optimizely client,
+ * flushing queued events and stopping datafile polling.
+ */
+declare const consentRevoked: OptimizelyStepExample;
+/**
+ * Consent granted -- no immediate SDK action needed. The destination
+ * re-initializes on the next push (walkerOS queues events until consent
+ * is granted, then re-inits). No calls expected.
+ */
+declare const consentGranted: OptimizelyStepExample;
+
+type step_OptimizelyStepExample = OptimizelyStepExample;
+declare const step_attributesOnlySkipTrack: typeof attributesOnlySkipTrack;
+declare const step_consentGranted: typeof consentGranted;
+declare const step_consentRevoked: typeof consentRevoked;
+declare const step_defaultEventForwarding: typeof defaultEventForwarding;
+declare const step_mappedEventName: typeof mappedEventName;
+declare const step_orderCompleteRevenue: typeof orderCompleteRevenue;
+declare const step_signupWithAttributes: typeof signupWithAttributes;
+declare const step_wildcardIgnored: typeof wildcardIgnored;
+declare namespace step {
+  export { type step_OptimizelyStepExample as OptimizelyStepExample, step_attributesOnlySkipTrack as attributesOnlySkipTrack, step_consentGranted as consentGranted, step_consentRevoked as consentRevoked, step_defaultEventForwarding as defaultEventForwarding, step_mappedEventName as mappedEventName, step_orderCompleteRevenue as orderCompleteRevenue, step_signupWithAttributes as signupWithAttributes, step_wildcardIgnored as wildcardIgnored };
+}
+
+declare const index_env: typeof env;
+declare const index_step: typeof step;
+declare namespace index {
+  export { index_env as env, index_step as step };
+}
+
+export { index as examples, index$1 as schemas };

package/dist/dev.d.ts

@@ -0,0 +1,193 @@
+import * as _walkeros_core_dev from '@walkeros/core/dev';
+import { z } from '@walkeros/core/dev';
+import { Mapping as Mapping$1, Flow } from '@walkeros/core';
+import { DestinationWeb } from '@walkeros/web-core';
+
+declare const SettingsSchema: z.ZodObject<{
+    sdkKey: z.ZodString;
+    userId: z.ZodOptional<z.ZodUnknown>;
+    attributes: z.ZodOptional<z.ZodUnknown>;
+    updateInterval: z.ZodOptional<z.ZodNumber>;
+    autoUpdate: z.ZodOptional<z.ZodBoolean>;
+    batchSize: z.ZodOptional<z.ZodNumber>;
+    flushInterval: z.ZodOptional<z.ZodNumber>;
+    skipOdp: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type Settings$1 = z.infer<typeof SettingsSchema>;
+
+declare const MappingSchema: z.ZodObject<{
+    eventKey: z.ZodOptional<z.ZodString>;
+    revenue: z.ZodOptional<z.ZodUnknown>;
+    value: z.ZodOptional<z.ZodUnknown>;
+    eventTags: z.ZodOptional<z.ZodUnknown>;
+    attributes: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+type Mapping = z.infer<typeof MappingSchema>;
+
+declare const settings: _walkeros_core_dev.JSONSchema;
+declare const mapping: _walkeros_core_dev.JSONSchema;
+
+type index$1_Mapping = Mapping;
+declare const index$1_MappingSchema: typeof MappingSchema;
+declare const index$1_SettingsSchema: typeof SettingsSchema;
+declare const index$1_mapping: typeof mapping;
+declare const index$1_settings: typeof settings;
+declare namespace index$1 {
+  export { type index$1_Mapping as Mapping, index$1_MappingSchema as MappingSchema, type Settings$1 as Settings, index$1_SettingsSchema as SettingsSchema, index$1_mapping as mapping, index$1_settings as settings };
+}
+
+/**
+ * Destination-level settings.
+ */
+interface Settings {
+    /** Optimizely Feature Experimentation SDK key. Required. */
+    sdkKey: string;
+    /** walkerOS mapping value to resolve userId for experiment bucketing. */
+    userId?: Mapping$1.Value;
+    /** User attributes for audience targeting, applied to every event. */
+    attributes?: Mapping$1.Value;
+    /** Polling interval for datafile updates in ms. Default: 60000. */
+    updateInterval?: number;
+    /** Auto-update datafile via polling. Default: true. */
+    autoUpdate?: boolean;
+    /** Batch event processor: events per batch. Default: 10. */
+    batchSize?: number;
+    /** Batch event processor: flush interval in ms. Default: 1000. */
+    flushInterval?: number;
+    /** Skip ODP manager initialization. Default: true. */
+    skipOdp?: boolean;
+    /** Runtime state -- not user-facing. Mutated by init/push. */
+    _state?: RuntimeState;
+}
+interface RuntimeState {
+    /** The Optimizely client instance (typed as OptimizelyClient). */
+    client?: OptimizelyClient;
+    /** Cached user context. Recreated when userId changes. */
+    userContext?: OptimizelyUserContext;
+    /** Last resolved userId to detect identity changes. */
+    lastUserId?: string;
+}
+/**
+ * OptimizelyClient -- the subset of the Optimizely SDK client the destination
+ * actually uses. Tests provide a mock via env.optimizely.
+ */
+interface OptimizelyClient {
+    onReady: () => Promise<{
+        success: boolean;
+    }>;
+    createUserContext: (userId: string, attributes?: Record<string, unknown>) => OptimizelyUserContext | null;
+    close: () => void;
+}
+/**
+ * OptimizelyUserContext -- user context methods the destination calls.
+ */
+interface OptimizelyUserContext {
+    trackEvent: (eventKey: string, eventTags?: Record<string, unknown>) => void;
+    setAttribute: (key: string, value: unknown) => void;
+}
+/**
+ * OptimizelySDK -- factory functions the destination imports from the SDK.
+ * Tests provide this via env.optimizely to avoid importing the real SDK.
+ */
+interface OptimizelySDK {
+    createInstance: (config: Record<string, unknown>) => OptimizelyClient;
+    createPollingProjectConfigManager: (config: Record<string, unknown>) => unknown;
+    createBatchEventProcessor: (config: Record<string, unknown>) => unknown;
+}
+/**
+ * Env -- optional SDK override. Production leaves env.optimizely undefined
+ * and the destination falls back to the real @optimizely/optimizely-sdk
+ * import. Tests provide a mock via env.optimizely.
+ */
+interface Env extends DestinationWeb.Env {
+    optimizely?: OptimizelySDK;
+}
+
+/**
+ * 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 };
+}
+
+/**
+ * Extended step example that may carry destination-level settings overrides.
+ */
+type OptimizelyStepExample = Flow.StepExample & {
+    settings?: Partial<Settings>;
+};
+/**
+ * Default event forwarding -- every walkerOS event becomes
+ * userContext.trackEvent(event.name). No mapping, no eventTags.
+ */
+declare const defaultEventForwarding: OptimizelyStepExample;
+/**
+ * Mapped event name -- mapping.name renames the event key for Optimizely.
+ * The eventKey must match an event created in the Optimizely project.
+ */
+declare const mappedEventName: OptimizelyStepExample;
+/**
+ * Revenue tracking -- mapping.settings.revenue resolves to an integer
+ * (cents). Passed as eventTags.revenue. The value is a pass-through;
+ * the user must provide cents (e.g. 55500 = $555.00).
+ */
+declare const orderCompleteRevenue: OptimizelyStepExample;
+/**
+ * Per-event attributes -- mapping.settings.attributes resolves to
+ * key-value pairs that are applied via setAttribute() before trackEvent().
+ */
+declare const signupWithAttributes: OptimizelyStepExample;
+/**
+ * Wildcard ignore -- walkerOS's standard way to drop events. The rule
+ * matches but does nothing. The destination fires zero SDK calls.
+ */
+declare const wildcardIgnored: OptimizelyStepExample;
+/**
+ * Skip track with attributes only -- fires setAttribute calls but no
+ * trackEvent. Useful for enriching user context without a conversion.
+ */
+declare const attributesOnlySkipTrack: OptimizelyStepExample;
+/**
+ * Consent revoked -- the destination closes the Optimizely client,
+ * flushing queued events and stopping datafile polling.
+ */
+declare const consentRevoked: OptimizelyStepExample;
+/**
+ * Consent granted -- no immediate SDK action needed. The destination
+ * re-initializes on the next push (walkerOS queues events until consent
+ * is granted, then re-inits). No calls expected.
+ */
+declare const consentGranted: OptimizelyStepExample;
+
+type step_OptimizelyStepExample = OptimizelyStepExample;
+declare const step_attributesOnlySkipTrack: typeof attributesOnlySkipTrack;
+declare const step_consentGranted: typeof consentGranted;
+declare const step_consentRevoked: typeof consentRevoked;
+declare const step_defaultEventForwarding: typeof defaultEventForwarding;
+declare const step_mappedEventName: typeof mappedEventName;
+declare const step_orderCompleteRevenue: typeof orderCompleteRevenue;
+declare const step_signupWithAttributes: typeof signupWithAttributes;
+declare const step_wildcardIgnored: typeof wildcardIgnored;
+declare namespace step {
+  export { type step_OptimizelyStepExample as OptimizelyStepExample, step_attributesOnlySkipTrack as attributesOnlySkipTrack, step_consentGranted as consentGranted, step_consentRevoked as consentRevoked, step_defaultEventForwarding as defaultEventForwarding, step_mappedEventName as mappedEventName, step_orderCompleteRevenue as orderCompleteRevenue, step_signupWithAttributes as signupWithAttributes, step_wildcardIgnored as wildcardIgnored };
+}
+
+declare const index_env: typeof env;
+declare const index_step: typeof step;
+declare namespace index {
+  export { index_env as env, index_step as step };
+}
+
+export { index as examples, index$1 as schemas };