feat: update client

Author: tilyupo

README.md

@@ -8,13 +8,12 @@ Part of the Replane project: [replane-dev/replane](https://github.com/replane-de
 
 ## Why it exists
 
-You just need: given a token + config name -> get the value. This package does only that, well:
+You just need: given a token + config name -> get the value. This package does only that:
 
 - Works in ESM and CJS (dual build)
 - Zero runtime deps (uses native `fetch` — bring a polyfill if your runtime lacks it)
 - Tiny bundle footprint
 - Strong TypeScript types
-- Resilient to server errors (returns your fallback and logs)
 
 ## Installation
 
@@ -37,27 +36,26 @@ const client = createReplaneClient({
 });
 
 // One-off fetch
-const featureFlag = await client.getConfigValue<boolean>({
-  name: "new-onboarding",
-  fallback: false,
-});
+
+const featureFlag = await client
+  .getConfigValue<boolean>("new-onboarding")
+  // Ignore errors and use `false` if config is missing or fetch fails
+  .catch(() => false);
 
 // Typed example
 interface PasswordRequirements {
   minLength: number;
   requireSymbol: boolean;
 }
 
-const passwordRequirements = await client.getConfigValue<PasswordRequirements>({
-  name: "password-requirements",
-  fallback: { minLength: 8, requireSymbol: false },
-});
+const passwordRequirements = await client
+  .getConfigValue<PasswordRequirements>("password-requirements")
+  .catch(() => ({ minLength: 8, requireSymbol: false }));
 
-// Watching a config
-const billingEnabled = await client.watchConfigValue<boolean>({
-  name: "billing-enabled",
-  fallback: false,
-});
+// Watching a config (initial fetch must succeed)
+const billingEnabled = await client.watchConfigValue<boolean>(
+  "billing-enabled"
+);
 
 // Later, read the latest value
 if (billingEnabled.get()) {
@@ -84,31 +82,32 @@ Returns an object: `{ getConfigValue, watchConfigValue, close }`.
 - `baseUrl` (string) – API origin (no trailing slash needed).
 - `apiKey` (string) – API key for authorization. Required.
 - `fetchFn` (function) – custom fetch (e.g. `undici.fetch` or mocked fetch in tests).
-- `timeoutMs` (number) – abort the request after N ms. Default: 1000.
-- `logger` (`{ debug(...), info(...), warn(...), error(...) }`) – optional logger (defaults to `console`).
+- `timeoutMs` (number) – abort the request after N ms. Default: 5000.
 
-### `client.getConfigValue({ name, fallback, ...overrides })`
+### `client.getConfigValue(name, overrides?)`
 
 Parameters:
 
 - `name` (string) – config name to fetch.
-- `fallback` (any) – value returned when request fails or response is invalid.
-- Overrides: `baseUrl`, `apiKey`, `fetchFn`, `timeoutMs`, `logger` – same semantics as in `createReplaneClient`.
+- Overrides: `baseUrl`, `apiKey`, `fetchFn`, `timeoutMs` – same semantics as in `createReplaneClient`.
 
-Returns: the config value (or the provided fallback on failure).
+Returns: a promise resolving to the parsed JSON value.
 
-Failures (non-2xx, network error, or invalid JSON) do not throw; the function logs via `logger.error(...)` and returns your `fallback`.
+Errors: throws on non-2xx responses (including 404 for missing configs), network errors, or invalid JSON. Catch `ReplaneError` to handle failures.
 
-### `client.watchConfigValue({ name, fallback, ...overrides })`
+### `client.watchConfigValue(name, overrides?)`
 
-Creates a lightweight watcher that refreshes the config value in the background (currently every 60 seconds). Useful for long‑lived processes wanting near‑real‑time updates without manually refetching.
+Creates a lightweight watcher that refreshes the config value in the background (every 60 seconds). Useful for long‑lived processes wanting near‑real‑time updates without manually refetching.
 
 Returns a promise resolving to an object: `{ get(): T, close(): void }`.
 
-- `get()` – returns the most recent value (initially the provided fallback until the first successful fetch).
+- `get()` – returns the most recent value.
 - `close()` – stops the periodic refresh for just this watcher. Further calls to `get()` after `close()` throw.
 
-Errors during refresh reuse the last known value.
+Notes:
+
+- The initial fetch must succeed (it will throw on errors).
+- Subsequent periodic refreshes update the stored value on success.
 
 #### Watcher lifecycle
 
@@ -119,10 +118,7 @@ Errors during refresh reuse the last known value.
 Example:
 
 ```ts
-const billingEnabled = await client.watchConfigValue({
-  name: "billing-enabled",
-  fallback: false,
-});
+const billingEnabled = await client.watchConfigValue("billing-enabled");
 if (billingEnabled.get()) {
   // ...
 }
@@ -141,7 +137,7 @@ client.close();
 
 ### Errors
 
-This SDK doesn't throw on request/response errors during `getConfigValue` or background refreshes in `watchConfigValue`. Instead, it logs (using the provided or default logger) and returns the provided `fallback` (or previous value for watchers).
+`getConfigValue` throws on non‑2xx HTTP responses (including 404), network errors, and invalid JSON. `watchConfigValue` uses `getConfigValue` for its initial fetch; handle errors accordingly with try/catch when creating a watcher. A `ReplaneError` is thrown for HTTP failures; other errors may be thrown for network/parse issues.
 
 ## Environment notes
 
@@ -157,20 +153,13 @@ interface LayoutConfig {
   variant: "a" | "b";
   ttl: number;
 }
-const layout = await client.getConfigValue<LayoutConfig>({
-  name: "layout",
-  fallback: { variant: "a", ttl: 0 },
-});
+const layout = await client.getConfigValue<LayoutConfig>("layout");
 ```
 
 Timeout override:
 
 ```ts
-await client.getConfigValue({
-  name: "slow-config",
-  fallback: null,
-  timeoutMs: 1500,
-});
+await client.getConfigValue("slow-config", { timeoutMs: 1500 });
 ```
 
 Custom fetch (tests):

src/index.ts

@@ -52,11 +52,9 @@ async function fetchWithTimeout(
   }
 }
 
-export interface GetConfigRequest<T> extends Partial<ReplaneClientOptions> {
-  /** Config name to fetch. */
-  name: string;
+export interface GetConfigOptions<T> extends Partial<ReplaneClientOptions> {
   /** Fallback value if config is not found. */
-  fallback: T;
+  fallback?: T;
 }
 
 export interface ConfigValueWatcher<T> {
@@ -68,15 +66,26 @@ export interface ConfigValueWatcher<T> {
 
 export interface ReplaneClient {
   /** Fetch a config value by name. */
-  getConfigValue<T = unknown>(req: GetConfigRequest<T>): Promise<T | undefined>;
+  getConfigValue<T = unknown>(
+    configName: string,
+    options?: GetConfigOptions<T>
+  ): Promise<T | undefined>;
   /** Watch a config value by name. */
   watchConfigValue<T = unknown>(
-    req: GetConfigRequest<T>
+    configName: string,
+    options?: GetConfigOptions<T>
   ): Promise<ConfigValueWatcher<T>>;
   /** Close the client and clean up resources. */
   close(): void;
 }
 
+export class ReplaneError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ReplaneError";
+  }
+}
+
 /**
  * Create a Replane client bound to an API key.
  * Usage:
@@ -89,36 +98,55 @@ export function createReplaneClient(
   if (!sdkOptions.apiKey) throw new Error("API key is required");
 
   async function getConfigValue<T = unknown>(
-    req: GetConfigRequest<T>
+    configName: string,
+    inputOptions: GetConfigOptions<T> = {}
   ): Promise<T> {
-    if (!req.name) throw new Error("config name is required");
-    const finalOptions = combineOptions(sdkOptions, req);
-    try {
-      return await _getConfig<T>({
-        configName: req.name,
-        fallback: req.fallback,
-        options: finalOptions,
-      });
-    } catch (err: unknown) {
-      finalOptions.logger.error("ReplaneClient.getConfig error", err);
-      return req.fallback;
+    const combinedOptions = combineOptions(sdkOptions, inputOptions);
+    const url = `${combinedOptions.baseUrl}/api/v1/configs/${encodeURIComponent(
+      configName
+    )}/value`;
+    const res = await fetchWithTimeout(
+      url,
+      {
+        method: "GET",
+        headers: {
+          Authorization: `Bearer ${combinedOptions.apiKey}`,
+          Accept: "application/json, text/plain;q=0.9, */*;q=0.8",
+        },
+      },
+      combinedOptions.timeoutMs,
+      combinedOptions.fetchFn
+    );
+
+    if (res.status === 404) {
+      throw new ReplaneError(`Config not found: ${configName}`);
     }
+
+    let body: unknown = await res.json();
+
+    if (!res.ok) {
+      throw new ReplaneError(
+        `Error fetching config "${configName}": ${res.status} ${
+          res.statusText
+        }${typeof body === "string" ? ` - ${body}` : ""}`
+      );
+    }
+
+    return body as T;
   }
 
   const watchers = new Set<ConfigValueWatcher<any>>();
 
   async function watchConfigValue<T = unknown>(
-    originalReq: GetConfigRequest<T>
+    configName: string,
+    originalOptions: GetConfigOptions<T> = {}
   ): Promise<ConfigValueWatcher<T>> {
-    const req = { ...originalReq };
-    let currentWatcherValue: T = await getConfigValue<T>(req);
+    const options = { ...originalOptions };
+    let currentWatcherValue: T = await getConfigValue<T>(configName, options);
     let isWatcherClosed = false;
 
     const intervalId = setInterval(async () => {
-      currentWatcherValue = await getConfigValue<T>({
-        ...req,
-        fallback: currentWatcherValue,
-      });
+      currentWatcherValue = await getConfigValue<T>(configName, options);
     }, 60_000);
 
     const watcher: ConfigValueWatcher<T> = {
@@ -152,75 +180,22 @@ export function createReplaneClient(
   }
 
   return {
-    getConfigValue: async (req) => {
+    getConfigValue: async (name, req) => {
       if (isClientClosed) {
         throw new Error("Replane client is closed");
       }
-      return await getConfigValue(req);
+      return await getConfigValue(name, req);
     },
-    watchConfigValue: async (req) => {
+    watchConfigValue: async (name, options) => {
       if (isClientClosed) {
         throw new Error("Replane client is closed");
       }
-      return await watchConfigValue(req);
+      return await watchConfigValue(name, options);
     },
     close,
   };
 }
 
-async function _getConfig<T>(params: {
-  configName: string;
-  fallback: T;
-  options: ReplaneFinalOptions;
-}): Promise<T> {
-  const url = `${params.options.baseUrl}/api/v1/configs/${encodeURIComponent(
-    params.configName
-  )}/value`;
-  const res = await fetchWithTimeout(
-    url,
-    {
-      method: "GET",
-      headers: {
-        Authorization: `Bearer ${params.options.apiKey}`,
-        Accept: "application/json, text/plain;q=0.9, */*;q=0.8",
-      },
-    },
-    params.options.timeoutMs,
-    params.options.fetchFn
-  );
-
-  let body: unknown = null;
-  const contentType = res.headers.get("content-type") || "";
-  try {
-    if (contentType.includes("application/json")) {
-      body = await res.json();
-    } else {
-      body = await res.text();
-    }
-  } catch (e) {
-    if (res.ok) {
-      params.options.logger.error("ReplaneClient.getConfig invalid response", {
-        name: params.configName,
-        status: res.status,
-        contentType,
-      });
-      return params.fallback;
-    }
-  }
-
-  if (!res.ok) {
-    params.options.logger.error("ReplaneClient.getConfig error", {
-      name: params.configName,
-      status: res.status,
-      body,
-    });
-
-    return params.fallback;
-  }
-
-  return body as T;
-}
-
 function combineOptions(
   defaults: ReplaneClientOptions,
   overrides: Partial<ReplaneClientOptions>