@coderule/clients 1.5.0 → 1.6.0

package/README.md

@@ -29,11 +29,12 @@ npm run build
 ### Unified client access
 
 ```typescript
-import { CoderuleClients } from '@coderule/clients';
+import { CoderuleClients, consoleLogger } from '@coderule/clients';
 
 const clients = new CoderuleClients({
   token: process.env.CODERULE_TOKEN!,
   auth: { baseUrl: 'https://r.coderule.ai:16803' }, // optional, defaults to this host
+  logger: consoleLogger, // optional, defaults to nullLogger (silent)
 });
 
 const snapshotStatus = await clients.sync.checkSnapshotStatus(snapshotHash);
@@ -257,13 +258,60 @@ const retrievalClient = new RetrievalHttpClient({
   baseUrl: 'http://localhost:8004',
   timeout: 30_000,
   jwtProvider: jwtFactory,
+  logger: consoleLogger, // optional
 });
 ```
 `CoderuleClients` also accepts per-service overrides via the `auth`, `ast`, `retrieval`,
 and `sync` options. `JWTFactory` exposes an `onTokenRefreshed` callback if you need to
 observe token rotations (for example, to log the current `server_url`).
 
-## Breaking Changes (v1.4.0)
+### Logging
+
+The SDK includes a flexible logging interface that allows you to integrate with any logging library:
+
+```typescript
+import { Logger, nullLogger, consoleLogger } from '@coderule/clients';
+
+// Use the built-in silent logger (default)
+const silentClients = new CoderuleClients({
+  token,
+  logger: nullLogger, // or omit for default
+});
+
+// Use the built-in console logger for debugging
+const debugClients = new CoderuleClients({
+  token,
+  logger: consoleLogger,
+});
+
+// Implement your own logger
+const customLogger: Logger = {
+  error: (message, ...meta) => myLogger.error(message, meta),
+  warn: (message, ...meta) => myLogger.warn(message, meta),
+  info: (message, ...meta) => myLogger.info(message, meta),
+  debug: (message, ...meta) => myLogger.debug(message, meta),
+};
+
+const clients = new CoderuleClients({
+  token,
+  logger: customLogger,
+});
+```
+
+All individual clients also accept an optional logger parameter:
+
+```typescript
+const authClient = new AuthHttpClient('http://localhost:8001', 30000, consoleLogger);
+```
+
+## Breaking Changes
+
+### v1.6.0
+- **Logger interface added**: All clients now accept an optional `logger` parameter
+- **Default behavior is silent**: By default, clients use `nullLogger` which produces no output
+- **Backward compatible**: The logger parameter is optional, existing code continues to work
+
+### v1.4.0
 
 - **Clients now require a JWT provider**: `SyncHttpClient`, `RetrievalHttpClient`, and
   `ASTHttpClient` no longer accept JWT strings per method. Inject a `JWTFactory` or any

package/dist/index.cjs

@@ -141,16 +141,37 @@ var FormData2 = fetchModule.FormData;
 var AbortController2 = fetchModule.AbortController;
 var fetch_wrapper_default = fetch2;
 
+// src/utils/logger.ts
+init_cjs_shims();
+var nullLogger = {
+  error: () => {
+  },
+  warn: () => {
+  },
+  info: () => {
+  },
+  debug: () => {
+  }
+};
+var consoleLogger = {
+  error: (message, ...meta) => console.error(message, ...meta),
+  warn: (message, ...meta) => console.warn(message, ...meta),
+  info: (message, ...meta) => console.info(message, ...meta),
+  debug: (message, ...meta) => console.debug(message, ...meta)
+};
+
 // src/clients/auth-client.ts
 var AuthHttpClient = class {
   /**
    * Initialize the Auth HTTP client
    * @param baseUrl - Base URL of the Auth service (e.g., "http://localhost:8001")
    * @param timeout - Request timeout in milliseconds (default: 30000)
+   * @param logger - Optional logger instance (defaults to nullLogger)
    */
-  constructor(baseUrl, timeout = 3e4) {
+  constructor(baseUrl, timeout = 3e4, logger) {
     this.baseUrl = baseUrl.replace(/\/$/, "");
     this.timeout = timeout;
+    this.logger = logger ?? nullLogger;
   }
   /**
    * Authenticate a token and receive a JWT
@@ -179,7 +200,7 @@ var AuthHttpClient = class {
         );
       }
       const data = await response.json();
-      console.debug(
+      this.logger.debug(
         `Authentication successful, JWT expires at ${data.expires_at}`
       );
       return data;
@@ -187,7 +208,7 @@ var AuthHttpClient = class {
       if (error.name === "AbortError") {
         throw new Error(`Request timeout after ${this.timeout}ms`);
       }
-      console.error(`Authentication request failed: ${error.message}`);
+      this.logger.error(`Authentication request failed: ${error.message}`);
       throw error;
     }
   }
@@ -213,13 +234,13 @@ var AuthHttpClient = class {
         );
       }
       const data = await response.json();
-      console.debug(`Health check: ${data.status}`);
+      this.logger.debug(`Health check: ${data.status}`);
       return data;
     } catch (error) {
       if (error.name === "AbortError") {
         throw new Error(`Request timeout after ${this.timeout}ms`);
       }
-      console.error(`Health check request failed: ${error.message}`);
+      this.logger.error(`Health check request failed: ${error.message}`);
       throw error;
     }
   }
@@ -229,7 +250,7 @@ var AuthHttpClient = class {
   close() {
   }
 };
-function decodeJWT(jwtToken) {
+function decodeJWT(jwtToken, logger) {
   try {
     const parts = jwtToken.split(".");
     if (parts.length !== 3) {
@@ -243,13 +264,13 @@ function decodeJWT(jwtToken) {
     if (payloadObj.exp) {
       const now = Math.floor(Date.now() / 1e3);
       if (payloadObj.exp < now) {
-        console.debug("JWT token is expired");
+        if (logger) logger.debug("JWT token is expired");
         return null;
       }
     }
     return payloadObj;
   } catch (error) {
-    console.error("Failed to decode JWT:", error);
+    if (logger) logger.error("Failed to decode JWT:", error);
     return null;
   }
 }
@@ -262,17 +283,20 @@ var SyncHttpClient = class {
    * @param config.baseUrl - URI/URL for connecting to the HTTP server (e.g., "http://localhost:8002")
    * @param config.timeout - Request timeout in milliseconds (default: 60000)
    * @param config.jwtProvider - Provider for obtaining JWT tokens
+   * @param config.logger - Optional logger instance (defaults to nullLogger)
    */
   constructor({
     baseUrl = "http://localhost:8002",
     timeout = 6e4,
-    jwtProvider
+    jwtProvider,
+    logger
   }) {
     if (!jwtProvider) {
       throw new Error("SyncHttpClient requires a JWT provider");
     }
     this.timeout = timeout;
     this.jwtProvider = jwtProvider;
+    this.logger = logger ?? nullLogger;
     this.configureBase(baseUrl);
   }
   updateBaseUrl(baseUrl) {
@@ -335,7 +359,7 @@ var SyncHttpClient = class {
       if (error.name === "AbortError") {
         throw new Error(`Request timeout after ${this.timeout}ms`);
       }
-      console.error(`Request failed: ${error.message}`);
+      this.logger.error(`Request failed: ${error.message}`);
       throw error;
     }
   }
@@ -370,7 +394,7 @@ var SyncHttpClient = class {
       clearTimeout(timeoutId);
       if (response.status === 422) {
         const data2 = await response.json();
-        console.info(
+        this.logger.info(
           `Snapshot ${snapshotHash.substring(0, 8)}... missing ${data2.missing_files?.length || 0} files`
         );
         return data2;
@@ -382,7 +406,7 @@ var SyncHttpClient = class {
         );
       }
       const data = await response.json();
-      console.info(
+      this.logger.info(
         `Snapshot ${snapshotHash.substring(0, 8)}... status: ${data.status}`
       );
       return data;
@@ -390,7 +414,7 @@ var SyncHttpClient = class {
       if (error.name === "AbortError") {
         throw new Error(`Request timeout after ${this.timeout}ms`);
       }
-      console.error(`Request failed: ${error.message}`);
+      this.logger.error(`Request failed: ${error.message}`);
       throw error;
     }
   }
@@ -429,7 +453,7 @@ var SyncHttpClient = class {
         );
       }
       const data = await response.json();
-      console.info(
+      this.logger.info(
         `Uploaded ${data.uploaded_count || 0} files, ${data.failed_count || 0} failed`
       );
       return data;
@@ -437,7 +461,7 @@ var SyncHttpClient = class {
       if (error.name === "AbortError") {
         throw new Error(`Request timeout after ${this.timeout}ms`);
       }
-      console.error(`Request failed: ${error.message}`);
+      this.logger.error(`Request failed: ${error.message}`);
       throw error;
     }
   }
@@ -493,7 +517,7 @@ var SyncHttpClient = class {
       if (error.name === "AbortError") {
         throw new Error(`Request timeout after ${this.timeout}ms`);
       }
-      console.error(`Request failed: ${error.message}`);
+      this.logger.error(`Request failed: ${error.message}`);
       throw error;
     }
   }
@@ -512,20 +536,23 @@ var RetrievalHttpClient = class {
    * @param config.baseUrl - URI/URL for connecting to the HTTP server (e.g., "http://localhost:8004")
    * @param config.timeout - Request timeout in milliseconds (default: 60000)
    * @param config.jwtProvider - Provider for obtaining JWT tokens
+   * @param config.logger - Optional logger instance (defaults to nullLogger)
    */
   constructor({
     baseUrl = "http://localhost:8004",
     timeout = 6e4,
-    jwtProvider
+    jwtProvider,
+    logger
   }) {
     if (!jwtProvider) {
       throw new Error("RetrievalHttpClient requires a JWT provider");
     }
     this.timeout = timeout;
     this.jwtProvider = jwtProvider;
+    this.logger = logger ?? nullLogger;
     this.configureBase(baseUrl);
-    console.debug(`Initialized HTTP client for ${this.baseUrl}`);
-    console.debug(`API base: ${this.apiBase}`);
+    this.logger.debug(`Initialized HTTP client for ${this.baseUrl}`);
+    this.logger.debug(`API base: ${this.apiBase}`);
   }
   updateBaseUrl(baseUrl) {
     this.configureBase(baseUrl);
@@ -554,7 +581,7 @@ var RetrievalHttpClient = class {
    */
   async healthCheck() {
     const healthEndpoint = `${this.apiBase}health`;
-    console.debug(`Checking server health: ${healthEndpoint}`);
+    this.logger.debug(`Checking server health: ${healthEndpoint}`);
     try {
       const controller = new AbortController2();
       const timeoutId = setTimeout(() => controller.abort(), this.timeout);
@@ -570,7 +597,7 @@ var RetrievalHttpClient = class {
         );
       }
       const healthInfo = await response.json();
-      console.debug(`HTTP retrieval server status:`, healthInfo);
+      this.logger.debug(`HTTP retrieval server status:`, healthInfo);
       return {
         status: healthInfo.status || "UNKNOWN",
         database: healthInfo.database || "UNKNOWN",
@@ -583,7 +610,7 @@ var RetrievalHttpClient = class {
       if (error.name === "AbortError") {
         throw new Error(`Request timeout after ${this.timeout}ms`);
       }
-      console.error(`Error checking HTTP server health: ${error.message}`);
+      this.logger.error(`Error checking HTTP server health: ${error.message}`);
       throw new Error(
         `Unable to connect to HTTP server ${this.baseUrl}: ${error.message}`
       );
@@ -647,7 +674,7 @@ var RetrievalHttpClient = class {
       const result = await response.json();
       const elapsedTime = (Date.now() - startTime) / 1e3;
       const formatter = options?.formatter || "standard";
-      console.debug(
+      this.logger.debug(
         `Retrieval query completed for snapshot ${snapshotHash.substring(0, 8)}... Formatter: ${formatter}. Total time: ${elapsedTime.toFixed(2)}s`
       );
       return result;
@@ -655,7 +682,7 @@ var RetrievalHttpClient = class {
       if (error.name === "AbortError") {
         throw new Error(`Request timeout after ${this.timeout}ms`);
       }
-      console.error(`Error executing retrieval query: ${error.message}`);
+      this.logger.error(`Error executing retrieval query: ${error.message}`);
       throw new Error(`Failed to execute retrieval query: ${error.message}`);
     }
   }
@@ -697,7 +724,7 @@ var RetrievalHttpClient = class {
         );
       }
       const statusInfo = await response.json();
-      console.debug(
+      this.logger.debug(
         `Snapshot ${snapshotHash.substring(0, 8)}... status: ${statusInfo.status}`
       );
       return statusInfo;
@@ -705,7 +732,7 @@ var RetrievalHttpClient = class {
       if (error.name === "AbortError") {
         throw new Error(`Request timeout after ${this.timeout}ms`);
       }
-      console.error(`Error checking snapshot status: ${error.message}`);
+      this.logger.error(`Error checking snapshot status: ${error.message}`);
       throw new Error(`Failed to check snapshot status: ${error.message}`);
     }
   }
@@ -735,13 +762,13 @@ var RetrievalHttpClient = class {
           `Cache clear failed with status ${response.status}: ${errorText}`
         );
       }
-      console.info("Graph cache cleared successfully");
+      this.logger.info("Graph cache cleared successfully");
       return true;
     } catch (error) {
       if (error.name === "AbortError") {
         throw new Error(`Request timeout after ${this.timeout}ms`);
       }
-      console.error(`Error clearing cache: ${error.message}`);
+      this.logger.error(`Error clearing cache: ${error.message}`);
       throw new Error(`Failed to clear cache: ${error.message}`);
     }
   }
@@ -772,7 +799,7 @@ var RetrievalHttpClient = class {
         );
       }
       const stats = await response.json();
-      console.debug(
+      this.logger.debug(
         `Cache stats: ${stats.cached_snapshots || 0} snapshots cached`
       );
       return stats;
@@ -780,7 +807,7 @@ var RetrievalHttpClient = class {
       if (error.name === "AbortError") {
         throw new Error(`Request timeout after ${this.timeout}ms`);
       }
-      console.error(`Error getting cache stats: ${error.message}`);
+      this.logger.error(`Error getting cache stats: ${error.message}`);
       throw new Error(`Failed to get cache stats: ${error.message}`);
     }
   }
@@ -824,17 +851,20 @@ var ASTHttpClient = class {
    * @param config.baseUrl - URI/URL for connecting to the HTTP server (e.g., "http://localhost:8003")
    * @param config.timeout - Request timeout in milliseconds (default: 60000)
    * @param config.jwtProvider - Provider for obtaining JWT tokens
+   * @param config.logger - Optional logger instance (defaults to nullLogger)
    */
   constructor({
     baseUrl = "http://localhost:8003",
     timeout = 6e4,
-    jwtProvider
+    jwtProvider,
+    logger
   }) {
     if (!jwtProvider) {
       throw new Error("ASTHttpClient requires a JWT provider");
     }
     this.timeout = timeout;
     this.jwtProvider = jwtProvider;
+    this.logger = logger ?? nullLogger;
     this.configureBase(baseUrl);
   }
   updateBaseUrl(baseUrl) {
@@ -891,7 +921,7 @@ var ASTHttpClient = class {
       if (error.name === "AbortError") {
         throw new Error(`Request timeout after ${this.timeout}ms`);
       }
-      console.error(`Failed to get visitor rules v2: ${error.message}`);
+      this.logger.error(`Failed to get visitor rules v2: ${error.message}`);
       throw error;
     }
   }
@@ -923,7 +953,7 @@ var ASTHttpClient = class {
       if (error.name === "AbortError") {
         throw new Error(`Request timeout after ${this.timeout}ms`);
       }
-      console.error(`Health check failed: ${error.message}`);
+      this.logger.error(`Health check failed: ${error.message}`);
       throw error;
     }
   }
@@ -996,6 +1026,7 @@ var JWTFactory = class {
     }
     this.minTtlMs = options.minTtlMs ?? DEFAULT_MIN_TTL_MS;
     this.onTokenRefreshed = options.onTokenRefreshed;
+    this.logger = options.logger ?? nullLogger;
   }
   setSourceToken(token) {
     if (!token) {
@@ -1034,7 +1065,7 @@ var JWTFactory = class {
       return await this.refreshPromise;
     } catch (error) {
       if (!forceRefresh && this.cache && now < this.cache.expiresAt) {
-        console.warn(
+        this.logger.warn(
           "Failed to refresh JWT, using cached token until expiry. Reason:",
           error
         );
@@ -1077,7 +1108,7 @@ var JWTFactory = class {
         return parsed;
       }
     }
-    const decoded = decodeJWT(jwt);
+    const decoded = decodeJWT(jwt, this.logger);
     if (decoded?.exp) {
       const expMs = decoded.exp * 1e3;
       if (expMs > referenceTime + this.minTtlMs) {
@@ -1098,7 +1129,7 @@ var JWTFactory = class {
       try {
         this.onTokenRefreshed(info);
       } catch (error) {
-        console.warn("JWTFactory onTokenRefreshed callback failed:", error);
+        this.logger.warn("JWTFactory onTokenRefreshed callback failed:", error);
       }
     }
   }
@@ -1133,14 +1164,16 @@ var CoderuleClients = class {
     if (!options?.token) {
       throw new Error("CoderuleClients requires a non-empty token");
     }
+    this.logger = options.logger ?? nullLogger;
     const overrides = resolveOverrides(options);
     const baseUrl = options.baseUrl;
     const authBase = overrides.auth?.baseUrl ?? baseUrl ?? DEFAULT_AUTH_BASE_URL;
     const authTimeout = resolveTimeout("auth", overrides);
-    this.auth = new AuthHttpClient(authBase, authTimeout);
+    this.auth = new AuthHttpClient(authBase, authTimeout, this.logger);
     const userTokenCallback = options.jwtFactory?.onTokenRefreshed;
     const jwtOptions = {
       ...options.jwtFactory,
+      logger: this.logger,
       onTokenRefreshed: (info) => {
         userTokenCallback?.(info);
         if (info.serverUrl) {
@@ -1158,17 +1191,20 @@ var CoderuleClients = class {
     this.ast = new ASTHttpClient({
       baseUrl: overrides.ast?.baseUrl ?? defaultServiceBase,
       timeout: resolveTimeout("ast", overrides),
-      jwtProvider: this.jwtFactory
+      jwtProvider: this.jwtFactory,
+      logger: this.logger
     });
     this.retrieval = new RetrievalHttpClient({
       baseUrl: overrides.retrieval?.baseUrl ?? defaultServiceBase,
       timeout: resolveTimeout("retrieval", overrides),
-      jwtProvider: this.jwtFactory
+      jwtProvider: this.jwtFactory,
+      logger: this.logger
     });
     this.sync = new SyncHttpClient({
       baseUrl: overrides.sync?.baseUrl ?? defaultServiceBase,
       timeout: resolveTimeout("sync", overrides),
-      jwtProvider: this.jwtFactory
+      jwtProvider: this.jwtFactory,
+      logger: this.logger
     });
     const initialServerUrl = this.jwtFactory.getServerUrl();
     if (initialServerUrl) {
@@ -1201,21 +1237,21 @@ var CoderuleClients = class {
         this.ast.updateBaseUrl(trimmed);
       }
     } catch (error) {
-      console.warn("Failed to update AST client base URL:", error);
+      this.logger.warn("Failed to update AST client base URL:", error);
     }
     try {
       if (!this.serviceBaseLocked.retrieval) {
         this.retrieval.updateBaseUrl(trimmed);
       }
     } catch (error) {
-      console.warn("Failed to update Retrieval client base URL:", error);
+      this.logger.warn("Failed to update Retrieval client base URL:", error);
     }
     try {
       if (!this.serviceBaseLocked.sync) {
         this.sync.updateBaseUrl(trimmed);
       }
     } catch (error) {
-      console.warn("Failed to update Sync client base URL:", error);
+      this.logger.warn("Failed to update Sync client base URL:", error);
     }
   }
 };
@@ -1226,7 +1262,9 @@ exports.CoderuleClients = CoderuleClients;
 exports.JWTFactory = JWTFactory;
 exports.RetrievalHttpClient = RetrievalHttpClient;
 exports.SyncHttpClient = SyncHttpClient;
+exports.consoleLogger = consoleLogger;
 exports.decodeJWT = decodeJWT;
 exports.fetch = fetch_wrapper_default;
+exports.nullLogger = nullLogger;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map