wardx 0.8.0 → 0.9.0

package/README.md

@@ -522,7 +522,15 @@ If there is no identified subject and you omit `{ subjectId }`, that call is not
 2. If there is no subject (`identify` unset and no `{ subjectId }`), return the Remote Config value.
 3. If an experiment applies to the subject, return the variant value.
 
-The SDK updates the snapshot when a sync response contains a newer `configVersion`. Until that sync, `config.get` returns the fallback or the last snapshot.
+The server first filters keys and experiments by role, then resolves any conditional base values against the instance's metadata and attributes. An applicable experiment still overrides that resolved base. Attributes do not change experiment eligibility, allocation, assignment, or exposure tracking.
+
+SDK 0.9.0 requires `@wardx/server` 0.9.0 or newer. Upgrade the server first: older servers reject the new client fields even when attributes are empty.
+
+Pass an optional flat `attributes` object to `createWardx`, for example `attributes: { os: 'android', build: 119, channel: 'stable' }`. Names are application-defined; values must be strings, finite numbers, or booleans. Wardx's `platform` identifies the SDK runtime (`node`, `csharp`, or `unity`), so use a custom attribute for the operating system. Attributes are shared by the SDK instance, not set per `config.get` subject; do not use an instance's attributes to switch between concurrent users.
+
+`wardx.setAttributes({ os: 'android', build: 120 })` replaces the entire attribute map with a copy. Use `{}` to clear it. The next successful sync resolves the new context; `await wardx.flush()` requests a sync now. Reads remain local and use the last snapshot until then. Attributes travel as client metadata; send only non-secret values.
+
+The SDK updates the snapshot when the project version or the resolved configuration changes. Every successful server response includes an opaque `configContext` token, which the SDK returns on subsequent syncs. The same contract applies with or without rules, allowing context changes to refresh values at the same `configVersion`. Until a successful sync, `config.get` returns the fallback or the last snapshot.
 
 ## Use case 10: Run an A/B experiment and record a goal
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wardx",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Node.js SDK for Wardx telemetry, Remote Config, and experiments.",
   "keywords": [
     "wardx",
@@ -37,6 +37,6 @@
     "src"
   ],
   "dependencies": {
-    "@wardx/core": "0.8.0"
+    "@wardx/core": "0.9.0"
   }
 }

package/src/WardxNode.js

@@ -18,6 +18,19 @@ const pkg = JSON.parse(
   readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8')
 );
 
+function copyAttributes(attributes) {
+  if (!attributes || typeof attributes !== 'object' || Array.isArray(attributes)) {
+    throw new Error('attributes must be an object');
+  }
+  for (const [key, value] of Object.entries(attributes)) {
+    if (key.length === 0) throw new Error('attributes keys must be non-empty strings');
+    if (typeof value !== 'string' && typeof value !== 'boolean' && !(typeof value === 'number' && Number.isFinite(value))) {
+      throw new Error(`attributes.${key} must be a string, finite number, or boolean`);
+    }
+  }
+  return Object.fromEntries(Object.entries(attributes));
+}
+
 export class WardxNode {
   constructor(settings) {
     this.settings = settings;
@@ -31,6 +44,8 @@ export class WardxNode {
       goal: (name, context) => this._core.experimentGoal(name, context)
     };
     if (this._disabled) return;
+    this._attributes = copyAttributes(settings.attributes === undefined ? {} : settings.attributes);
+    this._configContext = undefined;
     this._transport = createHttpTransport(settings);
     this._stopped = false;
     this._shutdownPromise = null;
@@ -54,6 +69,11 @@ export class WardxNode {
     this._core.identify(subjectId);
   }
 
+  setAttributes(attributes) {
+    if (this._disabled) return;
+    this._attributes = copyAttributes(attributes);
+  }
+
   counter(name, dims) {
     return this._core.counter(name, dims);
   }
@@ -126,7 +146,7 @@ export class WardxNode {
       this._core.snapshotIfDirty();
     }
     const frames = this._core.takePendingFrames();
-    if (!flags.bootstrap && frames.length === 0) return;
+    if (!flags.bootstrap && !flags.flush && frames.length === 0) return;
     const envelope = {
       protocol: PROTOCOL_VERSION,
       project: this.settings.project,
@@ -140,9 +160,11 @@ export class WardxNode {
         role: this.settings.role,
         appVersion: this.settings.appVersion,
         environment: this.settings.environment,
-        platform: PLATFORM
+        platform: PLATFORM,
+        attributes: this._attributes
       },
       configVersion: this._core.configStore.version,
+      configContext: this._configContext,
       frames
     };
     const json = JSON.stringify(envelope);
@@ -210,6 +232,7 @@ export class WardxNode {
     }
     if (json.config) {
       this._core.applyConfig(json.configVersion, json.config);
+      this._configContext = json.configContext;
     }
   }
 }

package/src/index.d.ts

@@ -80,6 +80,7 @@ export class WardxNode {
   constructor(settings: ResolvedSettings | DisabledWardxOptions);
   retentionActivity(userId: string): void;
   identify(subjectId: string | null | undefined): void;
+  setAttributes(attributes: Record<string, string | number | boolean>): void;
   counter(name: string, dims?: Dimensions | null): CounterHandle;
   gauge(name: string, dims?: Dimensions | null): GaugeHandle;
   histogram(name: string, a?: HistogramOptions | null, b?: HistogramOptions | null): HistogramHandle;