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

package/README.md

@@ -0,0 +1,248 @@
+# @walkeros/server-destination-amplitude
+
+Server-side Amplitude destination for walkerOS. Sends events to Amplitude via
+the `@amplitude/analytics-node` SDK with per-event identity, revenue, groups,
+eventOptions, and consent support.
+
+## Installation
+
+```bash
+npm install @walkeros/server-destination-amplitude
+```
+
+## Quick Start
+
+Minimal `flow.json` configuration:
+
+```json
+{
+  "destinations": {
+    "amplitude": {
+      "package": "@walkeros/server-destination-amplitude",
+      "config": {
+        "settings": {
+          "apiKey": "YOUR_AMPLITUDE_API_KEY"
+        }
+      }
+    }
+  }
+}
+```
+
+## Settings
+
+| Setting                        | Type             | Required | Default | Description                             |
+| ------------------------------ | ---------------- | -------- | ------- | --------------------------------------- |
+| `apiKey`                       | string           | Yes      | -       | Amplitude project API key               |
+| `serverZone`                   | `'US'` \| `'EU'` | No       | `'US'`  | Data residency zone                     |
+| `useBatch`                     | boolean          | No       | `false` | Use batch endpoint (higher rate limits) |
+| `flushIntervalMillis`          | number           | No       | `10000` | Flush interval in ms                    |
+| `flushQueueSize`               | number           | No       | `200`   | Max queued events before flush          |
+| `flushMaxRetries`              | number           | No       | `12`    | Max retries on failed flush             |
+| `minIdLength`                  | number           | No       | -       | Minimum length for user_id/device_id    |
+| `serverUrl`                    | string           | No       | -       | Custom server URL for proxies           |
+| `optOut`                       | boolean          | No       | `false` | Initial opt-out state                   |
+| `enableRequestBodyCompression` | boolean          | No       | `false` | Enable gzip compression                 |
+| `identify`                     | MappingValue     | No       | -       | Per-event identity resolution           |
+| `eventOptions`                 | MappingValue     | No       | -       | Per-event EventOptions                  |
+| `include`                      | string[]         | No       | -       | Event sections as event_properties      |
+
+## Identity (Per-Event EventOptions)
+
+Unlike the browser SDK, the Node SDK has no stateful `setUserId()` or
+`setDeviceId()`. Identity is passed per-event via `EventOptions` on every SDK
+call.
+
+```json
+{
+  "settings": {
+    "identify": {
+      "map": {
+        "user_id": "user.id",
+        "device_id": "user.device",
+        "session_id": "user.session"
+      }
+    }
+  }
+}
+```
+
+### Identify Operations (User Properties)
+
+Use per-rule mapping to set, increment, or clear user properties:
+
+```json
+{
+  "mapping": {
+    "user": {
+      "login": {
+        "skip": true,
+        "settings": {
+          "identify": {
+            "map": {
+              "user_id": "data.user_id",
+              "set": {
+                "map": {
+                  "plan": "data.plan",
+                  "company": "data.company"
+                }
+              },
+              "setOnce": {
+                "map": { "first_login": "timestamp" }
+              },
+              "add": {
+                "map": { "login_count": { "value": 1 } }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Supported identify operations: `set`, `setOnce`, `add`, `append`, `prepend`,
+`preInsert`, `postInsert`, `remove`, `unset`, `clearAll`.
+
+## Revenue
+
+### Single Product
+
+```json
+{
+  "mapping": {
+    "subscription": {
+      "renew": {
+        "skip": true,
+        "settings": {
+          "revenue": {
+            "map": {
+              "productId": "data.plan_id",
+              "price": "data.amount",
+              "revenueType": { "value": "renewal" },
+              "currency": { "key": "data.currency", "value": "USD" }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Multi-Product (Loop)
+
+```json
+{
+  "settings": {
+    "revenue": {
+      "loop": [
+        "nested",
+        {
+          "map": {
+            "productId": "data.id",
+            "price": "data.price",
+            "quantity": { "key": "data.quantity", "value": 1 },
+            "revenueType": { "value": "purchase" }
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+Revenue fields: `productId`, `price`, `quantity`, `revenueType`, `currency`,
+`revenue`, `receipt`, `receiptSig`, `eventProperties`.
+
+## Groups
+
+```json
+{
+  "settings": {
+    "group": {
+      "map": {
+        "type": { "value": "company" },
+        "name": "data.company"
+      }
+    },
+    "groupIdentify": {
+      "map": {
+        "type": { "value": "company" },
+        "name": "data.company",
+        "set": {
+          "map": {
+            "industry": "data.industry",
+            "size": "data.employee_count"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## EventOptions (time, insert_id, ip)
+
+Server-specific fields for offline/delayed events and deduplication:
+
+```json
+{
+  "settings": {
+    "eventOptions": {
+      "map": {
+        "time": "timestamp",
+        "insert_id": "id",
+        "ip": "context.ip"
+      }
+    }
+  }
+}
+```
+
+## Consent
+
+Declare required consent in `config.consent`. The destination toggles
+`amplitude.setOptOut()` when consent state changes.
+
+```json
+{
+  "config": {
+    "consent": { "analytics": true },
+    "settings": { "apiKey": "..." }
+  }
+}
+```
+
+## Destroy / Flush
+
+The destination calls `amplitude.flush()` on destroy to ensure all buffered
+events are sent before the process exits. This is critical for graceful server
+shutdown and short-lived processes.
+
+## Mapping Settings
+
+Per-rule mapping settings override destination-level settings:
+
+| Setting         | Type         | Description                                      |
+| --------------- | ------------ | ------------------------------------------------ |
+| `identify`      | MappingValue | Per-event identity (overrides destination-level) |
+| `revenue`       | MappingValue | Revenue data (single or loop)                    |
+| `group`         | MappingValue | Group assignment `{ type, name }`                |
+| `groupIdentify` | MappingValue | Group properties                                 |
+| `eventOptions`  | MappingValue | Per-rule EventOptions override                   |
+| `include`       | string[]     | Per-rule include (replaces destination-level)    |
+
+## SDK Call Mapping
+
+| walkerOS                  | Amplitude SDK Call                                            |
+| ------------------------- | ------------------------------------------------------------- |
+| Event push                | `amplitude.track(eventType, props, eventOptions)`             |
+| `settings.identify` (ops) | `amplitude.identify(Identify, eventOptions)`                  |
+| `settings.revenue`        | `amplitude.revenue(Revenue, eventOptions)`                    |
+| `settings.group`          | `amplitude.setGroup(type, name, eventOptions)`                |
+| `settings.groupIdentify`  | `amplitude.groupIdentify(type, name, Identify, eventOptions)` |
+| Consent revoked           | `amplitude.setOptOut(true)`                                   |
+| Consent granted           | `amplitude.setOptOut(false)`                                  |
+| Destroy                   | `amplitude.flush()`                                           |

package/dist/dev.d.mts

@@ -0,0 +1,287 @@
+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 { DestinationServer } from '@walkeros/server-core';
+
+declare const SettingsSchema: z.ZodObject<{
+    apiKey: z.ZodString;
+    serverZone: z.ZodOptional<z.ZodEnum<{
+        US: "US";
+        EU: "EU";
+    }>>;
+    flushIntervalMillis: z.ZodOptional<z.ZodNumber>;
+    flushQueueSize: z.ZodOptional<z.ZodNumber>;
+    flushMaxRetries: z.ZodOptional<z.ZodNumber>;
+    useBatch: z.ZodOptional<z.ZodBoolean>;
+    minIdLength: z.ZodOptional<z.ZodNumber>;
+    serverUrl: z.ZodOptional<z.ZodString>;
+    optOut: z.ZodOptional<z.ZodBoolean>;
+    enableRequestBodyCompression: z.ZodOptional<z.ZodBoolean>;
+    identify: z.ZodOptional<z.ZodUnknown>;
+    eventOptions: z.ZodOptional<z.ZodUnknown>;
+    include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+type Settings$1 = z.infer<typeof SettingsSchema>;
+
+declare const MappingSchema: z.ZodObject<{
+    identify: z.ZodOptional<z.ZodUnknown>;
+    revenue: z.ZodOptional<z.ZodUnknown>;
+    group: z.ZodOptional<z.ZodUnknown>;
+    groupIdentify: z.ZodOptional<z.ZodUnknown>;
+    eventOptions: z.ZodOptional<z.ZodUnknown>;
+    include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, 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 };
+}
+
+/**
+ * Amplitude SDK surface -- the subset of @amplitude/analytics-node the
+ * destination actually uses. Tests provide a mock via env.amplitude;
+ * production uses the real SDK import.
+ *
+ * Key difference from web: no setUserId/setDeviceId/setSessionId.
+ * Identity is per-event via EventOptions on every SDK call.
+ */
+interface AmplitudeSDK {
+    init: (apiKey: string, options?: Record<string, unknown>) => {
+        promise: Promise<void>;
+    };
+    track: (eventType: string, eventProperties?: Record<string, unknown>, eventOptions?: EventOptions) => void;
+    identify: (identify: IdentifyInstance, eventOptions?: EventOptions) => void;
+    revenue: (revenue: RevenueInstance, eventOptions?: EventOptions) => void;
+    setGroup: (groupType: string, groupName: string | string[], eventOptions?: EventOptions) => void;
+    groupIdentify: (groupType: string, groupName: string, identify: IdentifyInstance, eventOptions?: EventOptions) => void;
+    setOptOut: (optOut: boolean) => void;
+    flush: () => {
+        promise: Promise<void>;
+    };
+    Identify: new () => IdentifyInstance;
+    Revenue: new () => RevenueInstance;
+}
+/**
+ * Per-event identity and metadata fields. Passed to every SDK call.
+ * Maps directly to Amplitude's EventOptions type from the Node SDK.
+ */
+interface EventOptions {
+    user_id?: string;
+    device_id?: string;
+    session_id?: number;
+    time?: number;
+    insert_id?: string;
+    ip?: string;
+    city?: string;
+    country?: string;
+    region?: string;
+    language?: string;
+    platform?: string;
+    os_name?: string;
+    os_version?: string;
+    device_brand?: string;
+    device_manufacturer?: string;
+    device_model?: string;
+    app_version?: string;
+    carrier?: string;
+    user_agent?: string;
+    groups?: Record<string, unknown>;
+    plan?: Record<string, unknown>;
+    ingestion_metadata?: Record<string, unknown>;
+    partner_id?: string;
+    extra?: Record<string, unknown>;
+}
+/** Chainable Identify -- mirrors @amplitude/analytics-node Identify class. */
+interface IdentifyInstance {
+    set: (property: string, value: unknown) => IdentifyInstance;
+    setOnce: (property: string, value: unknown) => IdentifyInstance;
+    add: (property: string, value: number) => IdentifyInstance;
+    append: (property: string, value: unknown) => IdentifyInstance;
+    prepend: (property: string, value: unknown) => IdentifyInstance;
+    preInsert: (property: string, value: unknown) => IdentifyInstance;
+    postInsert: (property: string, value: unknown) => IdentifyInstance;
+    remove: (property: string, value: unknown) => IdentifyInstance;
+    unset: (property: string) => IdentifyInstance;
+    clearAll: () => IdentifyInstance;
+}
+/** Chainable Revenue -- mirrors @amplitude/analytics-node Revenue class. */
+interface RevenueInstance {
+    setProductId: (id: string) => RevenueInstance;
+    setPrice: (price: number) => RevenueInstance;
+    setQuantity: (quantity: number) => RevenueInstance;
+    setRevenueType: (type: string) => RevenueInstance;
+    setCurrency: (currency: string) => RevenueInstance;
+    setRevenue: (revenue: number) => RevenueInstance;
+    setReceipt: (receipt: string) => RevenueInstance;
+    setReceiptSig: (signature: string) => RevenueInstance;
+    setEventProperties: (properties: Record<string, unknown>) => RevenueInstance;
+}
+/**
+ * Destination-level settings. apiKey is required; all other fields
+ * are optional and passed through to the Amplitude Node SDK init().
+ */
+interface Settings {
+    apiKey: string;
+    serverZone?: 'US' | 'EU';
+    flushIntervalMillis?: number;
+    flushQueueSize?: number;
+    flushMaxRetries?: number;
+    useBatch?: boolean;
+    minIdLength?: number;
+    serverUrl?: string;
+    logLevel?: number;
+    optOut?: boolean;
+    offline?: boolean;
+    enableRequestBodyCompression?: boolean;
+    plan?: Record<string, unknown>;
+    ingestionMetadata?: Record<string, unknown>;
+    /** walkerOS mapping value for per-event identity resolution. */
+    identify?: Mapping$1.Value;
+    /** walkerOS mapping value for per-event EventOptions (time, insert_id, ip, etc). */
+    eventOptions?: Mapping$1.Value;
+    /** Sections to include as event_properties (e.g., ['data', 'globals']). */
+    include?: string[];
+}
+/**
+ * Env -- optional SDK override. Production leaves this undefined and the
+ * destination falls back to the real @amplitude/analytics-node import.
+ * Tests provide a mock via env.amplitude.
+ */
+interface Env extends DestinationServer.Env {
+    amplitude?: AmplitudeSDK;
+}
+
+declare const init: Env | undefined;
+declare const push: Env;
+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 type for Amplitude server destination.
+ * Settings and configInclude are read by the test runner and merged
+ * into the base destination configuration.
+ */
+type AmplitudeStepExample = Flow.StepExample & {
+    settings?: Partial<Settings>;
+    configInclude?: string[];
+};
+/**
+ * Default event forwarding -- every walkerOS event becomes
+ * amplitude.track(event.name, event_properties). With no mapping and
+ * no destination-level include, event_properties is `{}`.
+ */
+declare const defaultEventForwarding: AmplitudeStepExample;
+/**
+ * Wildcard ignore -- walkerOS's standard way to drop events. The rule
+ * matches but does nothing. The destination fires zero SDK calls.
+ */
+declare const wildcardIgnored: AmplitudeStepExample;
+/**
+ * Destination-level settings.include flattens the walkerOS `data` section
+ * into prefixed event_properties on every push.
+ */
+declare const destinationLevelInclude: AmplitudeStepExample;
+/**
+ * Destination-level settings.identify resolves per-event identity.
+ * Unlike the web destination (which uses setUserId/setDeviceId/setSessionId),
+ * server-side identity goes into EventOptions passed to every SDK call.
+ *
+ * user.session is 's3ss10n' (string). The destination deterministically
+ * hashes non-numeric session strings via djb2.
+ * djb2('s3ss10n') = 394324160.
+ */
+declare const destinationLevelIdentify: AmplitudeStepExample;
+/**
+ * Per-event identify with the full operation vocabulary -- this is the
+ * "user login" pattern: set user_id, enrich user properties. `skip: true`
+ * suppresses the default amplitude.track() call because we're running
+ * identity side effects only.
+ *
+ * Server-side, user_id is passed via EventOptions on identify().
+ */
+declare const userLoginIdentify: AmplitudeStepExample;
+/**
+ * Single-product revenue -- resolves `settings.revenue` to one object and
+ * fires one amplitude.revenue() call. Note the `{ key: "data.currency",
+ * value: "EUR" }` fallback syntax: try data.currency, default to "EUR".
+ *
+ * The custom event has no data.currency, so the fallback fires.
+ * `skip: true` suppresses the default track().
+ */
+declare const subscriptionRenewRevenue: AmplitudeStepExample;
+/**
+ * Multi-product order -- the canonical Amplitude ecommerce pattern.
+ * `revenue.loop: ["nested", { map: ... }]` iterates event.nested and
+ * resolves one revenue item per entry. Each becomes a separate
+ * amplitude.revenue() call. The order-level track() fires once with
+ * include-based event_properties.
+ *
+ * The default "order complete" fixture has 3 nested entries: two
+ * products (ers, cc) and one gift. Products have `data.price`; the
+ * gift has only `data.name`. The `condition` on the loop inner value
+ * filters to products only (price must be present).
+ */
+declare const orderCompleteMultiProduct: AmplitudeStepExample;
+/**
+ * Group assignment + group properties. Typically used for B2B products
+ * where a user belongs to a company. Both SDK calls fire on the same rule.
+ */
+declare const groupAssignmentWithProperties: AmplitudeStepExample;
+/**
+ * EventOptions mapping -- `settings.eventOptions` maps walkerOS fields
+ * to Amplitude per-event metadata. Here `time` maps from the event
+ * timestamp and `insert_id` maps from the event id for deduplication.
+ */
+declare const eventOptionsTimeInsertId: AmplitudeStepExample;
+/**
+ * Consent revoked -> amplitude.setOptOut(true). The destination checks
+ * the consent keys declared in config.consent and toggles optOut
+ * accordingly (strict: all required keys must be granted).
+ *
+ * Uses the canonical StepExample.command='consent' pattern: the test
+ * runner dispatches via elb('walker consent', in) instead of pushing
+ * an event.
+ */
+declare const consentRevokeOptOut: AmplitudeStepExample;
+/**
+ * Consent granted -> amplitude.setOptOut(false).
+ */
+declare const consentGrantOptIn: AmplitudeStepExample;
+
+type step_AmplitudeStepExample = AmplitudeStepExample;
+declare const step_consentGrantOptIn: typeof consentGrantOptIn;
+declare const step_consentRevokeOptOut: typeof consentRevokeOptOut;
+declare const step_defaultEventForwarding: typeof defaultEventForwarding;
+declare const step_destinationLevelIdentify: typeof destinationLevelIdentify;
+declare const step_destinationLevelInclude: typeof destinationLevelInclude;
+declare const step_eventOptionsTimeInsertId: typeof eventOptionsTimeInsertId;
+declare const step_groupAssignmentWithProperties: typeof groupAssignmentWithProperties;
+declare const step_orderCompleteMultiProduct: typeof orderCompleteMultiProduct;
+declare const step_subscriptionRenewRevenue: typeof subscriptionRenewRevenue;
+declare const step_userLoginIdentify: typeof userLoginIdentify;
+declare const step_wildcardIgnored: typeof wildcardIgnored;
+declare namespace step {
+  export { type step_AmplitudeStepExample as AmplitudeStepExample, step_consentGrantOptIn as consentGrantOptIn, step_consentRevokeOptOut as consentRevokeOptOut, step_defaultEventForwarding as defaultEventForwarding, step_destinationLevelIdentify as destinationLevelIdentify, step_destinationLevelInclude as destinationLevelInclude, step_eventOptionsTimeInsertId as eventOptionsTimeInsertId, step_groupAssignmentWithProperties as groupAssignmentWithProperties, step_orderCompleteMultiProduct as orderCompleteMultiProduct, step_subscriptionRenewRevenue as subscriptionRenewRevenue, step_userLoginIdentify as userLoginIdentify, 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 };