@coderule/clients 1.1.0 → 1.4.0

package/README.md

@@ -1,6 +1,6 @@
 # Coderule TypeScript Client SDK
 
-TypeScript HTTP clients for core Coderule microservices (Auth, Sync, Retrieval) with automatic fetch polyfill support.
+TypeScript HTTP clients for core Coderule microservices (Auth, Sync, Retrieval, AST) with automatic fetch polyfill support.
 
 ## Requirements
 
@@ -26,132 +26,190 @@ npm run build
 
 ## Usage Examples
 
-### Authentication Service
+### Unified client access
 
 ```typescript
-import { AuthHttpClient } from '@coderule/clients';
+import { CoderuleClients } from '@coderule/clients';
+
+const clients = new CoderuleClients({
+  token: process.env.CODERULE_TOKEN!,
+  auth: { baseUrl: 'https://r.coderule.ai:16803' }, // optional, defaults to this host
+});
+
+const snapshotStatus = await clients.sync.checkSnapshotStatus(snapshotHash);
+const retrieval = await clients.retrieval.query(snapshotHash, 'Find the entrypoint');
+const visitorRules = await clients.ast.getVisitorRulesV2();
+
+clients.close();
+```
+
+The unified client automatically exchanges your long-lived token for short-lived
+JWTs using the Auth service. Tokens are cached and refreshed halfway through
+their lifetime. Whenever the Auth service returns a JWT with a different
+`server_url`, the AST, Retrieval, and Sync clients update their base URLs on
+the fly.
+
+You can override individual service hosts or timeouts:
+
+```typescript
+const clients = new CoderuleClients({
+  token,
+  auth: { baseUrl: 'https://internal-auth.example.com' },
+  retrieval: { timeout: 90_000 },
+  sync: { baseUrl: 'http://localhost:8002' }, // static override keeps sync on localhost
+});
+```
+
+### Manual wiring
+
+If you prefer to manage dependency injection yourself, wire the Auth client and
+JWT factory and pass the provider into the other clients.
+
+```typescript
+import {
+  AuthHttpClient,
+  JWTFactory,
+  RetrievalHttpClient,
+  SyncHttpClient,
+  ASTHttpClient,
+} from '@coderule/clients';
 
+const authClient = new AuthHttpClient('http://localhost:8001');
+const jwtFactory = new JWTFactory(authClient, longLivedToken);
+
+const syncClient = new SyncHttpClient({
+  baseUrl: 'http://localhost:8002',
+  jwtProvider: jwtFactory,
+});
+
+const astClient = new ASTHttpClient({
+  baseUrl: 'http://localhost:8003',
+  jwtProvider: jwtFactory,
+});
+
+const retrievalClient = new RetrievalHttpClient({
+  baseUrl: 'http://localhost:8004',
+  jwtProvider: jwtFactory,
+});
+
+const status = await syncClient.checkSnapshotStatus(snapshotHash);
+const queryResult = await retrievalClient.query(snapshotHash, 'Find the entrypoint');
+const rules = await astClient.getVisitorRulesV2();
+```
+
+### Authentication service
+
+```typescript
 const authClient = new AuthHttpClient('http://localhost:8001');
 
 try {
-  // Authenticate and get JWT
   const authResponse = await authClient.authenticate('your-token');
-  const jwt = authResponse.jwt;
   console.log(`JWT expires at: ${authResponse.expires_at}`);
 
-  // Check health
   const health = await authClient.health();
   console.log(`Auth service status: ${health.status}`);
-} catch (error) {
-  console.error('Authentication failed:', error);
 } finally {
   authClient.close();
 }
 ```
 
-### Sync Service
+### Sync service
 
 ```typescript
-import { SyncHttpClient } from '@coderule/clients';
-
-const syncClient = new SyncHttpClient('http://localhost:8002', jwt);
+const syncClient = new SyncHttpClient({
+  baseUrl: 'http://localhost:8002',
+  jwtProvider: jwtFactory,
+});
+
+const files = [
+  { file_path: 'src/main.ts', content: 'const x = 1;' },
+  { file_path: 'src/utils.ts', content: 'export function util() {}' },
+  { file_path: 'package.json', content: '{"name": "test"}' },
+];
+
+const filesInfo = [];
+const fileHashes = [];
+const fileContents = new Map();
+
+for (const file of files) {
+  const fileHash = SyncHttpClient.calculateFileHash(file.file_path, file.content);
+  filesInfo.push({ file_path: file.file_path, file_hash: fileHash });
+  fileContents.set(fileHash, {
+    path: file.file_path,
+    content: Buffer.from(file.content),
+  });
+  fileHashes.push(fileHash);
+}
 
-try {
-  // Prepare files for sync (you need to provide the content)
-  const files = [
-    { file_path: 'src/main.ts', content: 'const x = 1;' },
-    { file_path: 'src/utils.ts', content: 'export function util() {}' },
-    { file_path: 'package.json', content: '{"name": "test"}' }
-  ];
-
-  // Calculate file hashes
-  const filesInfo = [];
-  const fileHashes = [];
-  const fileContents = new Map();
-
-  for (const file of files) {
-    const fileHash = SyncHttpClient.calculateFileHash(file.file_path, file.content);
-    filesInfo.push({
-      file_path: file.file_path,
-      file_hash: fileHash
-    });
-    fileContents.set(fileHash, {
-      path: file.file_path,
-      content: Buffer.from(file.content)
-    });
-    fileHashes.push(fileHash);
-  }
+const snapshotHash = SyncHttpClient.calculateSnapshotHash(fileHashes);
 
-  // Calculate snapshot hash
-  const snapshotHash = SyncHttpClient.calculateSnapshotHash(fileHashes);
-  console.log(`Snapshot hash: ${snapshotHash}`);
-
-  // Check if snapshot exists
-  const status = await syncClient.checkSnapshotStatus(snapshotHash);
-  console.log(`Snapshot status: ${status.status}`);
-
-  if (status.status === 'NOT_FOUND') {
-    // Create snapshot
-    const result = await syncClient.createSnapshot(snapshotHash, filesInfo);
-
-    // Upload missing files if needed
-    if (result.status === 'MISSING_CONTENT' && result.missing_files) {
-      const missingContent = new Map();
-      for (const missingFile of result.missing_files) {
-        if (fileContents.has(missingFile.file_hash)) {
-          missingContent.set(missingFile.file_hash, fileContents.get(missingFile.file_hash));
-        }
+const status = await syncClient.checkSnapshotStatus(snapshotHash);
+if (status.status === 'NOT_FOUND') {
+  const result = await syncClient.createSnapshot(snapshotHash, filesInfo);
+
+  if (result.status === 'MISSING_CONTENT' && result.missing_files) {
+    const missingContent = new Map();
+    for (const missingFile of result.missing_files) {
+      if (fileContents.has(missingFile.file_hash)) {
+        missingContent.set(
+          missingFile.file_hash,
+          fileContents.get(missingFile.file_hash)!,
+        );
       }
+    }
 
-      if (missingContent.size > 0) {
-        await syncClient.uploadFileContent(missingContent);
-        // Retry snapshot creation
-        await syncClient.createSnapshot(snapshotHash, filesInfo);
-      }
+    if (missingContent.size > 0) {
+      await syncClient.uploadFileContent(missingContent);
+      await syncClient.createSnapshot(snapshotHash, filesInfo);
     }
   }
-} catch (error) {
-  console.error('Sync failed:', error);
-} finally {
-  syncClient.close();
 }
 ```
 
-### Retrieval Service
+### AST service
 
 ```typescript
-import { RetrievalHttpClient } from '@coderule/clients';
+const astClient = new ASTHttpClient({
+  baseUrl: 'http://localhost:8003',
+  jwtProvider: jwtFactory,
+});
 
-const retrievalClient = new RetrievalHttpClient('http://localhost:8004');
+const health = await astClient.health();
+console.log(`AST service status: ${health.status}`);
 
-try {
-  // Execute a retrieval query
-  const result = await retrievalClient.query(
-    snapshotHash,
-    'Find the main authentication logic',
-    3000,  // budget tokens
-    jwt,
-    {
-      formatter: 'compact',
-      flow_strength: 1.5,
-      blend_alpha: 0.8
-    }
-  );
+const rules = await astClient.getVisitorRulesV2();
+console.log(`Rules format: ${rules.format}`);
 
-  console.log(result.formatted_output);
+const compiled = ASTHttpClient.compileRulesV2(rules);
+const ignoredPredicate = ASTHttpClient.buildIgnoredPredicate(compiled);
+```
 
-  // Check snapshot status
-  const status = await retrievalClient.checkSnapshotStatus(snapshotHash, jwt);
-  console.log(`Snapshot indexing status: ${status.status}`);
+### Retrieval service
 
-  // Get cache statistics
-  const cacheStats = await retrievalClient.getCacheStats(jwt);
-  console.log(`Cached snapshots: ${cacheStats.cached_snapshots}`);
-} catch (error) {
-  console.error('Retrieval failed:', error);
-} finally {
-  retrievalClient.close();
-}
+```typescript
+const retrievalClient = new RetrievalHttpClient({
+  baseUrl: 'http://localhost:8004',
+  jwtProvider: jwtFactory,
+});
+
+const result = await retrievalClient.query(
+  snapshotHash,
+  'Find the main authentication logic',
+  3000,
+  {
+    formatter: 'compact',
+    flow_strength: 1.5,
+    blend_alpha: 0.8,
+  },
+);
+
+console.log(result.formatted_output);
+
+const status = await retrievalClient.checkSnapshotStatus(snapshotHash);
+console.log(`Snapshot indexing status: ${status.status}`);
+
+const cacheStats = await retrievalClient.getCacheStats();
+console.log(`Cached snapshots: ${cacheStats.cached_snapshots}`);
 ```
 
 ## Utility Methods
@@ -195,8 +253,24 @@ All clients support timeout configuration in milliseconds:
 
 ```typescript
 // Custom timeout of 30 seconds
-const client = new RetrievalHttpClient('http://localhost:8004', 30000);
+const retrievalClient = new RetrievalHttpClient({
+  baseUrl: 'http://localhost:8004',
+  timeout: 30_000,
+  jwtProvider: jwtFactory,
+});
 ```
+`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)
+
+- **Clients now require a JWT provider**: `SyncHttpClient`, `RetrievalHttpClient`, and
+  `ASTHttpClient` no longer accept JWT strings per method. Inject a `JWTFactory` or any
+  `JWTProvider` implementation through the constructor instead.
+- **Unified entry point**: `CoderuleClients` centralises token exchange. Auth defaults to
+  `https://r.coderule.ai:16803`, and other clients automatically adopt the `server_url`
+  provided by the Auth service unless explicitly overridden.
 
 ## Notes
 
@@ -204,7 +278,10 @@ const client = new RetrievalHttpClient('http://localhost:8004', 30000);
 - **Optional dependency**: `node-fetch` is only required for Node.js versions < 18
 - **Zero dependencies for Node.js 18+**: Uses native fetch API
 - Clients automatically handle JSON serialization/deserialization
-- JWT tokens are required for most operations (except health checks)
+- JWT handling is centralised through a `JWTProvider` (`JWTFactory` or `CoderuleClients`)
+- AST, Retrieval, and Sync clients update their base URLs when the JWT refresh
+  returns a different `server_url` (unless a manual override is configured)
+- Health check endpoints don't require authentication
 - All clients have a `close()` method for consistency, though fetch doesn't maintain persistent connections
 
 ## Building from Source
@@ -221,4 +298,4 @@ npm run build
 
 ## License
 
-ISC
+ISC