vwo-fme-node-sdk 1.40.1 → 1.43.0

package/CHANGELOG.md

@@ -5,6 +5,122 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.43.0] - 2026-04-07
+
+### Added
+
+- Added support for whitelisting based on custom variables via `variationTargetingVariables` in the context. This allows users to be forcefully bucketed into specific variations based on custom evaluating rules, bypassing standard traffic allocation.
+
+  Example usage:
+
+  ```javascript
+  const vwoClient = await init({
+    accountId: '123456',
+    sdkKey: '32-alpha-numeric-sdk-key',
+  });
+
+  // Force users with 'premium' plan into a specific whitelisted variation
+  const userContext = {
+    id: 'user-123',
+    variationTargetingVariables: {
+      plan: 'premium',
+    },
+  };
+
+  const flag = await vwoClient.getFlag('feature-key', userContext);
+  ```
+
+- Added support for `isDevMode` in `userContext` that disables event dispatching for that user when enabled in both `userContext` and VWO settings.
+
+  Example usage:
+
+  ```javascript
+  const vwoClient = await init({
+    accountId: '123456',
+    sdkKey: '32-alpha-numeric-sdk-key',
+  });
+
+  // send isDevMode in userContext
+  const userContext = {
+    id: 'user-123',
+    isDevMode: true,
+  };
+
+  // Decisions are returned as normal, but events are not sent to DaCDN
+  const flag = await vwoClient.getFlag('feature-key', userContext);
+  await vwoClient.trackEvent('event-name', userContext, eventProperties);
+  ```
+
+## [1.42.0] - 2026-04-01
+
+### Added
+
+- Added a `shutdown()` API on `VWOClient` to support graceful teardown in long-running environments. Calling `shutdown()` now stops the internal settings polling loop, flushes any pending batched events, clears batch timers, and releases batching resources.
+
+  Example usage:
+
+  ```javascript
+  const { init } = require('vwo-fme-node-sdk');
+
+  (async () => {
+    const vwoClient = await init({
+      accountId: '123456',
+      sdkKey: '32-alpha-numeric-sdk-key',
+    });
+
+    // When your app/process is about to exit:
+    await vwoClient.shutdown();
+  })();
+  ```
+
+### Changed
+
+- Optimized the batch events queue to enforce `eventsPerRequest` as a hard per-dispatch cap, preserve event ordering when retries occur and avoid unnecessary timer wakeups when the queue is empty.
+- Improved Node.js HTTPS networking by introducing a configurable HTTPS agent (`httpsAgentConfig`) in the network layer, including validation and sensible defaults for `keepAlive`, `maxSockets`, `maxFreeSockets`, and `timeout` to provide better socket reuse and connection management.
+
+  Example usage:
+
+  ```javascript
+  const { init } = require('vwo-fme-node-sdk');
+
+  (async () => {
+    const vwoClient = await init({
+      accountId: '123456',
+      sdkKey: '32-alpha-numeric-sdk-key',
+      httpsAgentConfig: {
+        keepAlive: true, // default: true
+        maxSockets: 100, // default: 100, minimum 50
+        maxFreeSockets: 20, // default: 20, minimum 10
+        timeout: 60000, // in milliseconds, default: 60000, minimum 30000
+      },
+    });
+
+    // ...use the client...
+  })();
+  ```
+
+## [1.41.0] - 2026-03-18
+
+### Added
+
+- Added support for custom bucketing seed via `bucketingSeed` in the context. This allows users to bucket by a shared identifier instead of the individual user ID, ensuring all users within the same group receive the same variation.
+
+  Example usage:
+
+  ```javascript
+  const vwoClient = await init({
+    accountId: '123456',
+    sdkKey: '32-alpha-numeric-sdk-key',
+  });
+
+  // All employees of company-abc will get the same variation
+  const context = {
+    id: 'employee-123',
+    bucketingSeed: 'company-abc',
+  };
+  const flag = await vwoClient.getFlag('feature-key', context);
+  ```
+
 ## [1.40.1] - 2026-03-02
 
 ### Changed

package/README.md

@@ -98,6 +98,7 @@ To customize the SDK further, additional parameters can be passed to the `init()
 | `integrations`               | A callback function that receives data which can be pushed to any external tool that you need to integrate with.                                            | No           | Object   | See [Integrations](#integrations)             |
 | `batchEventData`             | Configuration for batch event processing to optimize network requests                                                                                       | No           | Object   | See [Batch Events](#batch-events) section     |
 | `retryConfig`                | Configuration for network request retry behavior and exponential backoff strategy                                                                           | No           | Object   | See [Retry Config](#retry-config) section     |
+| `httpsAgentConfig`           | Node.js HTTPS agent configuration for controlling keep-alive, socket pool size, and timeouts                                                                | No           | Object   | See [HTTPS Agent Config](#https-agent-config) |
 | `edgeConfig`                 | Configuration for edge/serverless environment optimizations (e.g., Cloudflare Workers)                                                                      | No           | Object   | See [Edge Config](#edge-config) section       |
 
 Refer to the [official VWO documentation](https://developers.vwo.com/v2/docs/fme-node-install) for additional parameter details.
@@ -110,12 +111,13 @@ The `context` object uniquely identifies users and is crucial for consistent fea
 
 The following table explains all the parameters in the `context` object:
 
-| **Parameter**     | **Description**                                                            | **Required** | **Type** | **Example**                       |
-| ----------------- | -------------------------------------------------------------------------- | ------------ | -------- | --------------------------------- |
-| `id`              | Unique identifier for the user.                                            | Yes          | String   | `'unique_user_id'`                |
-| `customVariables` | Custom attributes for targeting.                                           | No           | Object   | `{ age: 25, location: 'US' }`     |
-| `userAgent`       | User agent string for identifying the user's browser and operating system. | No           | String   | `'Mozilla/5.0 ... Safari/537.36'` |
-| `ipAddress`       | IP address of the user.                                                    | No           | String   | `'1.1.1.1'`                       |
+| **Parameter**     | **Description**                                                                                             | **Required** | **Type** | **Example**                       |
+| ----------------- | ----------------------------------------------------------------------------------------------------------- | ------------ | -------- | --------------------------------- |
+| `id`              | Unique identifier for the user.                                                                             | Yes          | String   | `'unique_user_id'`                |
+| `customVariables` | Custom attributes for targeting.                                                                            | No           | Object   | `{ age: 25, location: 'US' }`     |
+| `userAgent`       | User agent string for identifying the user's browser and operating system.                                  | No           | String   | `'Mozilla/5.0 ... Safari/537.36'` |
+| `ipAddress`       | IP address of the user.                                                                                     | No           | String   | `'1.1.1.1'`                       |
+| `bucketingSeed`   | Custom string used for bucketing instead of user `id`. See [Custom Bucketing Seed](#custom-bucketing-seed). | No           | String   | `'company-abc'`                   |
 
 #### Example
 
@@ -316,6 +318,25 @@ Behavior and validations:
 - For context usage, `context.id` must be a non-empty string (not an array); it is trimmed before use
 - `userId` and `aliasId` cannot be the same
 
+### Custom Bucketing Seed
+
+By default, the SDK uses the user `id` to determine which variation a user receives. The `bucketingSeed` option in the context lets you override this with a shared identifier (e.g., a company ID), so all users sharing the same seed are bucketed into the same variation.
+
+| **Parameter**   | **Description**                                         | **Required** | **Type** | **Example**     |
+| --------------- | ------------------------------------------------------- | ------------ | -------- | --------------- |
+| `bucketingSeed` | A custom string used for bucketing instead of user `id` | No           | String   | `'company-abc'` |
+
+#### Example Usage
+
+```javascript
+// All employees of company-abc will get the same variation
+const context = {
+  id: 'employee-123',
+  bucketingSeed: 'company-abc',
+};
+const flag = await vwoClient.getFlag('feature-key', context);
+```
+
 ### Storage
 
 The SDK operates in a stateless mode by default, meaning each `getFlag` call triggers a fresh evaluation of the flag against the current user context.
@@ -592,6 +613,32 @@ With this configuration, the retry delays would be:
 - 4th retry: 24 seconds (3 × 2^3)
 - 5th retry: 48 seconds (3 × 2^4)
 
+### HTTPS Agent Config
+
+The `httpsAgentConfig` option lets you customize the underlying Node.js HTTPS agent used by the SDK for network calls. This is useful when you need finer control over TCP connection reuse, socket pool sizing, and timeouts.
+
+| **Parameter**    | **Description**                                                         | **Required** | **Type** | **Default** | **Minimum** |
+| ---------------- | ----------------------------------------------------------------------- | ------------ | -------- | ----------- | ----------- |
+| `keepAlive`      | Reuse TCP connections so that multiple requests can use the same socket | No           | Boolean  | `true`      | —           |
+| `maxSockets`     | Maximum number of sockets allowed per host                              | No           | Number   | `100`       | `50`        |
+| `maxFreeSockets` | Maximum number of sockets to leave open in a free state                 | No           | Number   | `20`        | `10`        |
+| `timeout`        | Socket timeout in milliseconds                                          | No           | Number   | `60000`     | `30000`     |
+
+If any field is missing or below the minimum, the SDK uses the default value for that field.
+
+```javascript
+const vwoClient = await init({
+  accountId: '123456',
+  sdkKey: '32-alpha-numeric-sdk-key',
+  httpsAgentConfig: {
+    keepAlive: true,
+    maxSockets: 100,
+    maxFreeSockets: 20,
+    timeout: 60000, // in milliseconds -- this is socket timeout
+  },
+});
+```
+
 ### Edge Config
 
 The `edgeConfig` option enables edge/serverless environment optimizations. This configuration should only be passed in serverless environments (e.g., Cloudflare Workers). When used in Cloudflare environments, events are automatically flushed using `ctx.waitUntil(vwoClient.flushEvents());` to ensure proper event tracking after execution completes.

package/dist/VERSION.js

@@ -1 +1 @@
-module.exports = { version: "1.40.1" };
+module.exports = { version: "1.43.0" };