chore: add autogenerated replaneClientId context prop

Author: tilyupo

packages/sdk/src/client.ts

@@ -12,9 +12,16 @@ import type {
 import { ReplaneRemoteStorage } from "./storage";
 import { ReplaneError, ReplaneErrorCode } from "./error";
 import { evaluateOverrides } from "./evaluation";
-import { Deferred } from "./utils";
+import { Deferred, generateClientId } from "./utils";
 import { DEFAULT_AGENT } from "./version";
 
+/**
+ * The context key for the auto-generated client ID.
+ * This key is automatically set by the SDK and can be used for segmentation.
+ * User-provided values for this key take precedence over the auto-generated value.
+ */
+export const REPLANE_CLIENT_ID_KEY = "replaneClientId";
+
 interface ReplaneHandle<T extends object> {
   _replane: ReplaneImpl<T>;
 }
@@ -106,7 +113,13 @@ class ReplaneImpl<T extends object = Record<string, unknown>> {
    */
   constructor(options: ReplaneOptions<T> = {}) {
     this.logger = options.logger ?? console;
-    this.context = { ...(options.context ?? {}) };
+
+    // Generate replaneClientId and set it as base context.
+    // User-provided context values take precedence (merged on top).
+    const autoGeneratedContext: ReplaneContext = {
+      [REPLANE_CLIENT_ID_KEY]: generateClientId(),
+    };
+    this.context = { ...autoGeneratedContext, ...(options.context ?? {}) };
 
     // Initialize configs from snapshot or defaults
     const initialConfigs: ConfigDto[] = [];

packages/sdk/src/index.ts

@@ -1,6 +1,5 @@
 // Re-export public API
 
-// Client class
 export { Replane } from "./client";
 
 // Error types

packages/sdk/src/utils.ts

@@ -1,3 +1,22 @@
+/**
+ * Generates a random UUID using the Web Crypto API.
+ * Falls back to a simple implementation if crypto.randomUUID is not available.
+ *
+ * @returns A random UUID string
+ */
+export function generateClientId(): string {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+
+  // Fallback for older environments
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0;
+    const v = c === "x" ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
+}
+
 /**
  * Returns a promise that resolves after the specified delay
  *

packages/sdk/tests/index.spec.ts

@@ -3,6 +3,8 @@ import { Replane, ReplaneError } from "../src/index";
 import type { ReplaneSnapshot, ConnectOptions } from "../src/index";
 import { MockReplaneServerController } from "./utils";
 
+const REPLANE_CLIENT_ID_KEY = "replaneClientId";
+
 function sync() {
   return new Promise((resolve) => setTimeout(resolve, 0));
 }
@@ -48,12 +50,14 @@ describe("Replane", () => {
       defaults,
       context,
     });
-    return client.connect({
-      sdkKey: "test-sdk-key",
-      baseUrl: "https://replane.my-host.com",
-      fetchFn: mockServer.fetchFn,
-      ...connectOptions,
-    }).then(() => client);
+    return client
+      .connect({
+        sdkKey: "test-sdk-key",
+        baseUrl: "https://replane.my-host.com",
+        fetchFn: mockServer.fetchFn,
+        ...connectOptions,
+      })
+      .then(() => client);
   }
 
   describe("basic config fetching", () => {
@@ -1715,7 +1719,6 @@ describe("Replane", () => {
         unsubscribe3();
       });
     });
-
   });
 
   describe("client close", () => {
@@ -2125,6 +2128,147 @@ describe("Replane with snapshot", () => {
     });
   });
 
+  describe("replaneClientId auto-generation", () => {
+    it("should auto-generate replaneClientId in client context", () => {
+      const snapshot: ReplaneSnapshot<Record<string, unknown>> = {
+        configs: [
+          {
+            name: "feature",
+            value: "default",
+            overrides: [
+              {
+                name: "segmented-override",
+                conditions: [
+                  {
+                    operator: "segmentation",
+                    property: REPLANE_CLIENT_ID_KEY,
+                    fromPercentage: 0,
+                    toPercentage: 100,
+                    seed: "test-seed",
+                  },
+                ],
+                value: "segmented-value",
+              },
+            ],
+          },
+        ],
+      };
+
+      // Create client without providing replaneClientId
+      const client = new Replane({ snapshot });
+
+      // Should match segmentation because replaneClientId is auto-generated
+      expect(client.get("feature")).toBe("segmented-value");
+    });
+
+    it("should allow user to override replaneClientId", () => {
+      const userProvidedClientId = "user-provided-client-id";
+      const snapshot: ReplaneSnapshot<Record<string, unknown>> = {
+        configs: [
+          {
+            name: "feature",
+            value: "default",
+            overrides: [
+              {
+                name: "user-override",
+                conditions: [
+                  {
+                    operator: "equals",
+                    property: REPLANE_CLIENT_ID_KEY,
+                    value: userProvidedClientId,
+                  },
+                ],
+                value: "user-override-value",
+              },
+            ],
+          },
+        ],
+      };
+
+      // Provide replaneClientId in context - should take precedence
+      const client = new Replane({
+        snapshot,
+        context: { [REPLANE_CLIENT_ID_KEY]: userProvidedClientId },
+      });
+
+      expect(client.get("feature")).toBe("user-override-value");
+    });
+
+    it("should allow per-request context to override replaneClientId", () => {
+      const perRequestClientId = "per-request-client-id";
+      const snapshot: ReplaneSnapshot<Record<string, unknown>> = {
+        configs: [
+          {
+            name: "feature",
+            value: "default",
+            overrides: [
+              {
+                name: "per-request-override",
+                conditions: [
+                  {
+                    operator: "equals",
+                    property: REPLANE_CLIENT_ID_KEY,
+                    value: perRequestClientId,
+                  },
+                ],
+                value: "per-request-value",
+              },
+            ],
+          },
+        ],
+      };
+
+      const client = new Replane({ snapshot });
+
+      // Default should be based on auto-generated ID
+      expect(client.get("feature")).toBe("default");
+
+      // Per-request context should override the auto-generated ID
+      expect(
+        client.get("feature", { context: { [REPLANE_CLIENT_ID_KEY]: perRequestClientId } })
+      ).toBe("per-request-value");
+    });
+
+    it("should generate unique replaneClientId for each client instance", () => {
+      const snapshot: ReplaneSnapshot<Record<string, unknown>> = {
+        configs: [
+          {
+            name: "feature",
+            value: "default",
+            overrides: [
+              {
+                name: "50-percent-rollout",
+                conditions: [
+                  {
+                    operator: "segmentation",
+                    property: REPLANE_CLIENT_ID_KEY,
+                    fromPercentage: 0,
+                    toPercentage: 50,
+                    seed: "test-seed",
+                  },
+                ],
+                value: "rollout-value",
+              },
+            ],
+          },
+        ],
+      };
+
+      // Create multiple clients
+      const clients = Array.from({ length: 10 }, () => new Replane({ snapshot }));
+
+      // Each client should get a consistent result (either default or rollout-value)
+      // but different clients may get different results due to unique IDs
+      const results = clients.map((client) => client.get("feature"));
+
+      // At least verify we get both values (statistically very likely with 10 clients and 50% rollout)
+      // This test mainly verifies that the segmentation is actually working
+      expect(
+        results.some((r) => r === "rollout-value") || results.some((r) => r === "default")
+      ).toBe(true);
+    });
+  });
+
   describe("overrides evaluation", () => {
     it("should evaluate equals operator", () => {
       const snapshot: ReplaneSnapshot<Record<string, unknown>> = {

packages/sdk/tests/utils.spec.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { delay, retryDelay, combineAbortSignals, Deferred } from "../src/utils";
+import { delay, retryDelay, combineAbortSignals, Deferred, generateClientId } from "../src/utils";
 
 describe("delay", () => {
   beforeEach(() => {
@@ -221,3 +221,23 @@ describe("Deferred", () => {
     await expect(chainedPromise).resolves.toBe(42);
   });
 });
+
+describe("generateClientId", () => {
+  it("should generate a valid UUID string", () => {
+    const clientId = generateClientId();
+
+    // UUID format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    expect(clientId).toMatch(uuidRegex);
+  });
+
+  it("should generate unique IDs on each call", () => {
+    const id1 = generateClientId();
+    const id2 = generateClientId();
+    const id3 = generateClientId();
+
+    expect(id1).not.toBe(id2);
+    expect(id2).not.toBe(id3);
+    expect(id1).not.toBe(id3);
+  });
+});