chore: update naming

Author: tilyupo

packages/sdk/README.md

@@ -98,16 +98,20 @@ Type parameter `T` defines the shape of your configs (a mapping of config names
 
 #### Options
 
-- `baseUrl` (string) – Replane origin (no trailing slash needed).
+- `baseUrl` (string) – Replane origin (no trailing slash needed). Required.
 - `sdkKey` (string) – SDK key for authorization. Required. **Note:** Each SDK key is tied to a specific project and can only access configs from that project. To access configs from multiple projects, create multiple SDK keys and initialize separate client instances.
 - `required` (object or array) – mark specific configs as required. If any required config is missing, the client will throw an error during initialization. Can be an object with boolean values or an array of config names. Optional.
-- `fallbacks` (object) – fallback values to use if the initial request to fetch configs fails. Allows the client to start even when the API is unavailable. Optional.
+- `defaults` (object) – default values to use if the initial request to fetch configs fails or times out. These values are used immediately while waiting for server connection. Allows the client to start even when the API is unavailable. Optional.
 - `context` (object) – default context for all config evaluations. Can be overridden per-request in `get()`. Optional.
 - `fetchFn` (function) – custom fetch (e.g. `undici.fetch` or mocked fetch in tests). Optional.
-- `timeoutMs` (number) – abort the request after N ms. Default: 2000.
-- `retries` (number) – number of retry attempts on failures (5xx or network errors). Default: 2.
-- `retryDelayMs` (number) – base delay between retries in ms (a small jitter is applied). Default: 200.
+- `requestTimeoutMs` (number) – timeout for SSE requests in ms. Default: 2000.
+- `initializationTimeoutMs` (number) – timeout for SDK initialization in ms. Default: 5000.
+- `retryDelayMs` (number) – base delay between retries in ms. Default: 200.
+- `inactivityTimeoutMs` (number) – timeout for SSE inactivity before reconnecting in ms. Default: 30000.
 - `logger` (object) – custom logger with `debug`, `info`, `warn`, `error` methods. Default: `console`.
+- `agent` (string) – agent identifier sent in User-Agent header.
+- `onConnectionError` (function) – callback invoked when a connection error occurs during SSE streaming.
+- `onConnected` (function) – callback invoked when the SSE connection is successfully established.
 
 ### `replane.get<K>(name, options?)`
 
@@ -383,7 +387,7 @@ const replane = await createReplaneClient<Configs>({
 // If any required config is missing, initialization will throw
 ```
 
-### Fallback configs
+### Default configs
 
 ```ts
 interface Configs {
@@ -395,15 +399,15 @@ interface Configs {
 const replane = await createReplaneClient<Configs>({
   sdkKey: process.env.REPLANE_SDK_KEY!,
   baseUrl: "https://replane.my-host.com",
-  fallbacks: {
+  defaults: {
     "feature-flag": false, // Use false if fetch fails
     "max-connections": 10, // Use 10 if fetch fails
     "timeout-ms": 5000, // Use 5s if fetch fails
   },
 });
 
-// If the initial fetch fails, fallback values are used
-// Once the configs client connects, it will receive realtime updates
+// If the initial fetch fails or times out, default values are used
+// Once the client connects, it will receive realtime updates
 const maxConnections = replane.get("max-connections"); // 10 (or real value)
 ```
 

packages/sdk/src/client-types.ts

@@ -163,17 +163,17 @@ export interface ReplaneClientOptions<T extends object> {
     | Array<keyof T>;
 
   /**
-   * Fallback values to use if the initial request to fetch configs fails.
-   * When provided, all configs must be specified.
+   * Default values to use if the initial request to fetch configs fails or times out.
+   * These values are used immediately while waiting for server connection.
    * @example
    * {
-   *   fallbacks: {
+   *   defaults: {
    *     config1: "value1",
    *     config2: 42,
    *   },
    * }
    */
-  fallbacks?: {
+  defaults?: {
     [K in keyof T]: T[K];
   };
 
@@ -283,7 +283,7 @@ export interface ReplaneFinalOptions {
   retryDelayMs: number;
   context: ReplaneContext;
   requiredConfigs: string[];
-  fallbacks: ConfigDto[];
+  defaults: ConfigDto[];
   agent: string;
   onConnectionError?: (error: unknown) => void;
   onConnected?: () => void;

packages/sdk/src/client.ts

@@ -323,7 +323,7 @@ async function createReplaneClientInternal<T extends object = Record<string, unk
   storage: ReplaneStorage
 ): Promise<ReplaneClient<T>> {
   const { client, configs, startStreaming, clientReady } = createClientCore<T>({
-    initialConfigs: sdkOptions.fallbacks,
+    initialConfigs: sdkOptions.defaults,
     context: sdkOptions.context,
     logger: sdkOptions.logger,
     storage,
@@ -337,8 +337,8 @@ async function createReplaneClientInternal<T extends object = Record<string, unk
   });
 
   const initializationTimeoutId = setTimeout(() => {
-    if (sdkOptions.fallbacks.length === 0) {
-      // no fallbacks, we have nothing to work with
+    if (sdkOptions.defaults.length === 0) {
+      // no defaults, we have nothing to work with
       client.close();
 
       clientReady.reject(
@@ -404,7 +404,7 @@ function toFinalOptions<T extends object>(options: ReplaneClientOptions<T>): Rep
       : Object.entries(options.required ?? {})
           .filter(([_, value]) => value !== undefined)
           .map(([name]) => name),
-    fallbacks: Object.entries(options.fallbacks ?? {})
+    defaults: Object.entries(options.defaults ?? {})
       .filter(([_, value]) => value !== undefined)
       .map(([name, value]) => ({
         name,

packages/sdk/tests/index.spec.ts

@@ -1379,7 +1379,7 @@ describe("createReplaneClient", () => {
     });
   });
 
-  describe("initialization and fallbacks", () => {
+  describe("initialization and defaults", () => {
     it("should not throw error when SDK key is missing", async () => {
       await expect(
         createReplaneClient({
@@ -1392,9 +1392,9 @@ describe("createReplaneClient", () => {
       ).rejects.toThrow("Replane client initialization timed out");
     });
 
-    it("should use fallbacks and timeout when server does not respond", async () => {
+    it("should use defaults and timeout when server does not respond", async () => {
       clientPromise = createClient<Record<string, unknown>>({
-        fallbacks: { config1: "fallback-value" },
+        defaults: { config1: "fallback-value" },
         initializationTimeoutMs: 50,
       });
 
@@ -1403,27 +1403,27 @@ describe("createReplaneClient", () => {
       expect(client.get("config1")).toBe("fallback-value");
     });
 
-    it("should throw timeout error when no fallbacks and server does not respond", async () => {
+    it("should throw timeout error when no defaults and server does not respond", async () => {
       clientPromise = createClient({
         initializationTimeoutMs: 50,
       });
 
       await expect(clientPromise).rejects.toThrow("Replane client initialization timed out");
     });
 
-    it("should throw error when required config is missing from fallbacks", async () => {
+    it("should throw error when required config is missing from defaults", async () => {
       clientPromise = createClient<Record<string, unknown>>({
-        fallbacks: { config1: "fallback-value" },
+        defaults: { config1: "fallback-value" },
         required: ["config1", "config2"],
         initializationTimeoutMs: 50,
       });
 
       await expect(clientPromise).rejects.toThrow("Required configs are missing: config2");
     });
 
-    it("should succeed when all required configs are in fallbacks", async () => {
+    it("should succeed when all required configs are in defaults", async () => {
       clientPromise = createClient<Record<string, unknown>>({
-        fallbacks: { config1: "fallback1", config2: "fallback2" },
+        defaults: { config1: "fallback1", config2: "fallback2" },
         required: ["config1", "config2"],
         initializationTimeoutMs: 50,
       });
@@ -1433,9 +1433,9 @@ describe("createReplaneClient", () => {
       expect(client.get("config2")).toBe("fallback2");
     });
 
-    it("should override fallbacks with server values", async () => {
+    it("should override defaults with server values", async () => {
       clientPromise = createClient<Record<string, unknown>>({
-        fallbacks: { config1: "fallback-value" },
+        defaults: { config1: "fallback-value" },
       });
       const connection = await mockServer.acceptConnection();
       await connection.push({
@@ -1450,7 +1450,7 @@ describe("createReplaneClient", () => {
 
     it("should accept required as object format", async () => {
       clientPromise = createClient<Record<string, unknown>>({
-        fallbacks: { config1: "fallback1", config2: "fallback2" },
+        defaults: { config1: "fallback1", config2: "fallback2" },
         required: { config1: true, config2: true },
         initializationTimeoutMs: 50,
       });
@@ -1461,7 +1461,7 @@ describe("createReplaneClient", () => {
 
     it("should handle empty required array", async () => {
       clientPromise = createClient<Record<string, unknown>>({
-        fallbacks: { config1: "fallback1" },
+        defaults: { config1: "fallback1" },
         required: [],
         initializationTimeoutMs: 50,
       });
@@ -1470,7 +1470,7 @@ describe("createReplaneClient", () => {
       expect(client.get("config1")).toBe("fallback1");
     });
 
-    it("should call onConnectionError callback when initial connection fails with fallbacks", async () => {
+    it("should call onConnectionError callback when initial connection fails with defaults", async () => {
       const onConnectionError = vi.fn();
       const failingFetch = vi.fn().mockRejectedValue(new Error("Connection refused"));
 
@@ -1479,7 +1479,7 @@ describe("createReplaneClient", () => {
         baseUrl: "https://replane.my-host.com",
         fetchFn: failingFetch,
         logger: silentLogger,
-        fallbacks: { config1: "fallback-value" },
+        defaults: { config1: "fallback-value" },
         initializationTimeoutMs: 50,
         retryDelayMs: 10,
         onConnectionError,