blockintel-gate-sdk 0.4.0 → 0.4.1

package/README.md

@@ -408,27 +408,11 @@ The SDK includes a **Heartbeat Manager** that automatically acquires and refresh
 
 ### How It Works
 
-1. **Per-Signer Token Cache**: The heartbeat manager maintains a `Map<signerId, SignerHeartbeatEntry>` so each signer gets its own cached token, refresh timer, and backoff state. Switching between signers never invalidates other signers' tokens.
-2. **Automatic Token Acquisition**: When `getTokenForSigner(signerId)` is called, the manager returns the cached token immediately if valid, or acquires a new one on demand. The initial default signer is pre-warmed on `start()`.
-3. **Per-Signer Refresh**: Each signer entry has its own background `setTimeout` timer that refreshes the token before expiry (default every 10 seconds + jitter + backoff on failure).
-4. **LRU Eviction**: When the number of concurrent signer entries exceeds `maxSigners` (default: 20), the least-recently-used entry is evicted.
-5. **Idle TTL Eviction**: A background timer (every 60s) evicts signer entries not used within `signerIdleTtlMs` (default: 5 minutes).
-6. **Local Rate Limiting**: Per-signer guard prevents re-requesting within `localRateLimitMs` (default: 2.1s) to avoid hammering the Control Plane.
-7. **Token Inclusion**: The heartbeat token is automatically included in the `signingContext` of every evaluation request.
-
-### Multi-Signer Support
-
-Trading desks running 3+ bot profiles no longer experience `HEARTBEAT_MISSING` errors when switching signers. Each signer's token is cached independently:
-
-```typescript
-// KMS wrapper automatically uses the correct signer from KeyId
-const protectedKms = gate.wrapKmsClient(kmsClient);
-
-// These calls use independent heartbeat tokens — no cross-invalidation
-await protectedKms.sign({ KeyId: 'alias/bot-1', Message: tx1, ... });
-await protectedKms.sign({ KeyId: 'alias/bot-2', Message: tx2, ... });
-await protectedKms.sign({ KeyId: 'alias/bot-1', Message: tx3, ... }); // cache hit
-```
+1. **Automatic Token Acquisition**: The SDK automatically starts a background heartbeat refresher when the `GateClient` is initialized. This continuously sends heartbeats to the Control Plane, keeping the signer status active in the UI.
+2. **Token Refresh**: Heartbeat tokens are refreshed every 10 seconds (configurable via `heartbeatRefreshIntervalSeconds`) to maintain a valid token
+3. **Signing Enforcement**: Before any `evaluate()` call, the SDK checks for a valid heartbeat token. If missing or expired, it throws `HEARTBEAT_MISSING` error
+4. **Token Inclusion**: The heartbeat token is automatically included in the `signingContext` of every evaluation request
+5. **No Manual Scripts Needed**: The SDK handles all heartbeat management automatically - no need for separate heartbeat scripts
 
 ### Configuration
 
@@ -442,11 +426,8 @@ const gate = new GateClient({
   // Heartbeat manager uses baseUrl to infer Control Plane URL
   // Or explicitly set controlPlaneUrl if different
   controlPlaneUrl: 'https://control-plane.blockintelai.com',  // Optional
-  signerId: 'my-signer-id',  // Optional: default signerId for heartbeat (if known upfront)
+  signerId: 'my-signer-id',  // Optional: signerId for heartbeat (if known upfront)
   heartbeatRefreshIntervalSeconds: 10,  // Optional: heartbeat refresh interval (default: 10s)
-  maxSigners: 20,             // Optional: max concurrent signer entries (default: 20)
-  signerIdleTtlMs: 300000,    // Optional: evict idle signers after this many ms (default: 5 min)
-  localRateLimitMs: 2100,     // Optional: min ms between acquire attempts per signer (default: 2.1s)
 });
 ```
 
@@ -477,17 +458,23 @@ try {
 
 ### Heartbeat Manager API
 
-The primary API is `getTokenForSigner()`, which handles cache lookup, on-demand acquisition, and waiting:
+The heartbeat manager is internal to the SDK, but you can access it if needed:
 
 ```typescript
-// Get token for a specific signer
-const token = await gate.heartbeatManager.getTokenForSigner('my-signer-id', 2000);
+// Check if heartbeat is valid
+const isValid = gate.heartbeatManager.isValid();
+
+// Get current heartbeat token (if valid)
+const token = gate.heartbeatManager.getToken();
+
+// Update signer ID (called automatically when signer is known)
+gate.heartbeatManager.updateSignerId('new-signer-id');
 
-// Stop heartbeat manager and clean up all timers (e.g., on shutdown)
+// Stop heartbeat refresher (e.g., on shutdown)
 gate.heartbeatManager.stop();
 ```
 
-**Note**: The KMS wrapper automatically calls `getTokenForSigner()` with the correct signer ID extracted from `KeyId`, so manual token management is typically not needed.
+**Note**: The heartbeat manager automatically updates the `signerId` when using the KMS wrapper, so manual updates are typically not needed.
 
 ## Secret Rotation
 

package/dist/index.cjs

@@ -1315,7 +1315,7 @@ var HeartbeatManager = class {
     this.started = true;
     this.startEvictionTimer();
     this.getTokenForSigner(this.defaultSignerId, 0).catch((error) => {
-      console.error("[HEARTBEAT] Failed to acquire initial heartbeat:", error instanceof Error ? error.message : error);
+      console.warn("[HEARTBEAT] Failed to acquire initial heartbeat:", error instanceof Error ? error.message : error);
     });
   }
   startEvictionTimer() {