@nullbridge/sdk 1.0.3 → 1.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nullbridge/sdk",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "NullBridge AI Agent Identity Governance SDK",
   "main": "src/index.js",
   "types": "src/index.d.ts",

package/src/agents.js

@@ -9,34 +9,36 @@ class AgentRegistry {
   constructor(config, http) {
     this._config = config;
     this._http   = http;
-    this._agents = new Map(); // local cache
+    this._agents = new Map();
   }
 
   /**
    * Register a new AI agent with NullBridge.
    *
    * @param {object} options
+   * @param {string} [options.id]        - Stable unique identifier. Auto-generated if omitted.
    * @param {string} options.name        - Human-readable agent name (e.g. 'claims-processor')
    * @param {string} options.type        - Agent type: 'llm' | 'rpa' | 'workflow' | 'custom'
    * @param {string} [options.model]     - Model name (e.g. 'gpt-4o', 'claude-3-5-sonnet')
-   * @param {string[]} [options.scopes]  - What this agent is allowed to do (e.g. ['read:claims', 'write:reports'])
-   * @param {object} [options.metadata]  - Any additional metadata
+   * @param {string[]} [options.scopes]  - Permission scopes (e.g. ['read:claims', 'write:reports'])
+   * @param {object} [options.metadata]  - Additional metadata
+   * @param {number} [options.heartbeatInterval] - Heartbeat interval in ms (default: 60000)
    * @returns {Promise<Agent>}
    */
   async register(options = {}) {
     if (!options.name) throw new Error('[NullBridge] agent.name is required');
     if (!options.type) throw new Error('[NullBridge] agent.type is required');
 
-    const agentId = this._generateAgentId(options.name);
+    const agentId = options.id || this._generateAgentId(options.name);
 
     const payload = {
-      id:         agentId,
-      name:       options.name,
-      type:       options.type,
-      model:      options.model     || null,
-      scopes:     options.scopes    || [],
-      metadata:   options.metadata  || {},
-      sdk_version: '1.0.0',
+      id:            agentId,
+      name:          options.name,
+      type:          options.type,
+      model:         options.model    || null,
+      scopes:        options.scopes   || [],
+      metadata:      options.metadata || {},
+      sdk_version:   '1.0.3',
       registered_at: Math.floor(Date.now() / 1000),
     };
 
@@ -47,13 +49,20 @@ class AgentRegistry {
         { license_key: this._config.licenseKey, agent: payload }
       );
 
-      const agent = status === 200 || status === 201
+      const agent = (status === 200 || status === 201)
         ? { ...payload, ...body.agent, _registered: true }
         : { ...payload, _registered: false, _local: true };
 
       this._agents.set(agentId, agent);
       console.info(`[NullBridge] Agent registered: ${options.name} (${agentId})`);
-      return new Agent(agent, this._config, this._http);
+
+      const instance = new Agent(agent, this._config, this._http);
+
+      // Start heartbeat automatically
+      const heartbeatMs = options.heartbeatInterval || 60000;
+      instance.startHeartbeat(heartbeatMs);
+
+      return instance;
 
     } catch (err) {
       // API unreachable — register locally and continue
@@ -103,9 +112,10 @@ class AgentRegistry {
  */
 class Agent {
   constructor(data, config, http) {
-    this._data   = data;
-    this._config = config;
-    this._http   = http;
+    this._data             = data;
+    this._config           = config;
+    this._http             = http;
+    this._heartbeatTimer   = null;
 
     // Expose agent properties
     this.id       = data.id;
@@ -166,9 +176,10 @@ class Agent {
   }
 
   /**
-   * Deregister this agent — revokes its identity and credentials
+   * Deregister this agent — revokes its identity and stops heartbeat
    */
   async deregister() {
+    this.stopHeartbeat();
     try {
       await this._http.post(
         this._config.apiUrl,
@@ -181,6 +192,50 @@ class Agent {
     }
   }
 
+  /**
+   * Send a heartbeat to update last_seen in the dashboard.
+   * Called automatically by startHeartbeat() — you don't need to call this manually.
+   */
+  async heartbeat() {
+    try {
+      await this._http.post(
+        this._config.apiUrl,
+        `/sdk/agents/${this.id}/heartbeat`,
+        { license_key: this._config.licenseKey }
+      );
+      if (this._config.debug) {
+        console.debug(`[NullBridge] Heartbeat sent: ${this.name}`);
+      }
+    } catch {
+      // Silently fail — heartbeat is best-effort
+    }
+  }
+
+  /**
+   * Start sending periodic heartbeats to keep last_seen current in the dashboard.
+   * Called automatically after register(). You only need this if you stopped it manually.
+   *
+   * @param {number} [intervalMs=60000] - How often to ping in milliseconds
+   */
+  startHeartbeat(intervalMs = 60000) {
+    if (this._heartbeatTimer) return; // already running
+    // Send immediately on start
+    this.heartbeat();
+    this._heartbeatTimer = setInterval(() => this.heartbeat(), intervalMs);
+    // Allow Node.js to exit even if heartbeat is still running
+    if (this._heartbeatTimer.unref) this._heartbeatTimer.unref();
+  }
+
+  /**
+   * Stop sending heartbeats. Called automatically by deregister() and shutdown().
+   */
+  stopHeartbeat() {
+    if (this._heartbeatTimer) {
+      clearInterval(this._heartbeatTimer);
+      this._heartbeatTimer = null;
+    }
+  }
+
   toJSON() {
     return {
       id: this.id, name: this.name, type: this.type,

package/src/errors.js

@@ -0,0 +1,36 @@
+'use strict';
+
+/**
+ * NullBridgeLicenseError — thrown when license validation fails
+ */
+class NullBridgeLicenseError extends Error {
+  constructor(reason, message) {
+    super(message || `NullBridge license error: ${reason}. Contact brian@nullbridge.ai.`);
+    this.name   = 'NullBridgeLicenseError';
+    this.reason = reason;
+  }
+}
+
+/**
+ * NullBridgeApiError — thrown when the NullBridge API returns an error
+ */
+class NullBridgeApiError extends Error {
+  constructor(status, message, code) {
+    super(message || `NullBridge API error (${status})${code ? ': ' + code : ''}`);
+    this.name   = 'NullBridgeApiError';
+    this.status = status;
+    this.code   = code;
+  }
+}
+
+/**
+ * NullBridgeCredentialError — thrown for credential operation failures
+ */
+class NullBridgeCredentialError extends Error {
+  constructor(message) {
+    super(`[NullBridge] Credential error: ${message}`);
+    this.name = 'NullBridgeCredentialError';
+  }
+}
+
+module.exports = { NullBridgeLicenseError, NullBridgeApiError, NullBridgeCredentialError };

package/src/index.js

@@ -7,41 +7,25 @@ const { AuditLogger }      = require('./audit');
 const { AnomalyDetector }  = require('./anomaly');
 const { SiemStreamer }      = require('./siem');
 const { HttpClient }        = require('./http');
+const { NullBridgeLicenseError, NullBridgeApiError, NullBridgeCredentialError } = require('./errors');
+
+const SDK_VERSION = '1.0.5';
 
-const SDK_VERSION = '1.0.0';
-
-/**
- * NullBridge SDK
- * AI Agent Identity Governance Platform
- *
- * @example
- * const { NullBridge } = require('@nullbridge/sdk');
- *
- * const nb = new NullBridge({
- *   licenseKey: process.env.NULLBRIDGE_LICENSE_KEY,
- * });
- *
- * await nb.init();
- * const agent = await nb.agents.register({ name: 'my-agent', type: 'llm' });
- */
 class NullBridge {
   /**
    * @param {object} config
    * @param {string} config.licenseKey         - Your NullBridge license key (NB-XXXX-XXXX-XXXX-XXXX)
-   * @param {string} [config.serverUrl]        - License server URL (default: https://nullbridge-license-server-production.up.railway.app)
    * @param {string} [config.apiUrl]           - NullBridge API URL (default: https://api.nullbridge.ai)
-   * @param {boolean} [config.skipLicense]     - Skip license check (for development only)
+   * @param {string} [config.serverUrl]        - License server URL (default: https://nullbridge-license-server-production.up.railway.app)
+   * @param {boolean} [config.skipLicense]     - Skip license check (for local development only)
    * @param {boolean} [config.autoShutdown]    - Shut down process if license is revoked (default: true)
-   * @param {number} [config.checkInterval]    - License check interval in ms (default: 86400000 — 24 hours)
-   * @param {object} [config.siem]             - SIEM streaming config
-   * @param {string} [config.siem.endpoint]    - SIEM webhook URL
-   * @param {string} [config.siem.format]      - Log format: 'json' | 'cef' | 'leef' (default: 'json')
-   * @param {boolean} [config.debug]           - Enable debug logging
+   * @param {number} [config.checkInterval]    - License recheck interval in ms (default: 86400000 — 24h)
+   * @param {boolean} [config.debug]           - Enable verbose logging
    */
   constructor(config = {}) {
     if (!config.licenseKey && !config.skipLicense) {
-      throw new Error(
-        '[NullBridge] licenseKey is required. Set NULLBRIDGE_LICENSE_KEY in your environment variables.\n' +
+      throw new NullBridgeLicenseError('NO_KEY',
+        '[NullBridge] licenseKey is required. Set NULLBRIDGE_LICENSE_KEY in your environment.\n' +
         'Contact brian@nullbridge.ai to obtain a license key.'
       );
     }
@@ -61,7 +45,6 @@ class NullBridge {
     this._licenseData = null;
     this._http        = new HttpClient(this._config);
 
-    // Sub-modules — available after init()
     this.license     = new LicenseClient(this._config, this._http);
     this.agents      = new AgentRegistry(this._config, this._http);
     this.credentials = new CredentialVault(this._config, this._http);
@@ -69,15 +52,15 @@ class NullBridge {
     this.anomaly     = new AnomalyDetector(this._config, this._http);
     this.siem        = this._config.siem ? new SiemStreamer(this._config, this._http) : null;
 
-    this._log('NullBridge SDK v' + SDK_VERSION + ' initialized');
+    this._log(`NullBridge SDK v${SDK_VERSION} initialized`);
   }
 
   /**
    * Initialize NullBridge — validates license and starts background services.
-   * Call this once on application startup, before serving traffic.
+   * Call once on application startup before serving traffic.
    *
-   * @returns {Promise<NullBridge>} — returns this for chaining
-   * @throws {Error} if license is invalid or expired
+   * @returns {Promise<NullBridge>}
+   * @throws {NullBridgeLicenseError} if license is invalid or expired
    */
   async init() {
     if (this._initialized) {
@@ -87,17 +70,26 @@ class NullBridge {
 
     this._log('Initializing...');
 
-    // Validate license
     if (!this._config.skipLicense) {
-      this._licenseData = await this.license.validate();
-      this._log(`License valid — customer: ${this._licenseData.customer}, plan: ${this._licenseData.plan}`);
+      try {
+        this._licenseData = await this.license.validate();
+        this._log(`License valid — customer: ${this._licenseData.customer}, plan: ${this._licenseData.plan}`);
+      } catch (err) {
+        if (err instanceof NullBridgeLicenseError) {
+          // Re-throw with clear message
+          throw new NullBridgeLicenseError(err.reason,
+            `[NullBridge] Cannot initialize — ${err.message}`
+          );
+        }
+        throw err;
+      }
 
       // Start periodic license checks
       this.license.startWatcher((valid, reason) => {
         if (!valid) {
-          console.error(`[NullBridge] License revoked: ${reason}`);
+          console.error(`[NullBridge] License revoked: ${reason}. Contact brian@nullbridge.ai.`);
           if (this._config.autoShutdown) {
-            console.error('[NullBridge] Shutting down in 60 seconds. Contact brian@nullbridge.ai.');
+            console.error('[NullBridge] Shutting down in 60 seconds.');
             setTimeout(() => process.exit(1), 60 * 1000);
           }
         }
@@ -106,19 +98,18 @@ class NullBridge {
       this._log('License check skipped (development mode)');
     }
 
-    // Start SIEM streaming if configured
     if (this.siem) {
       await this.siem.start();
       this._log('SIEM streaming started');
     }
 
     this._initialized = true;
-    console.info('[NullBridge] Ready');
+    console.info(`[NullBridge] Ready — SDK v${SDK_VERSION}`);
     return this;
   }
 
   /**
-   * Gracefully shut down NullBridge — flushes audit logs and stops watchers.
+   * Gracefully shut down — flushes audit logs, stops heartbeats, stops watchers.
    */
   async shutdown() {
     this._log('Shutting down...');
@@ -129,7 +120,7 @@ class NullBridge {
   }
 
   /**
-   * Returns current license data (customer, plan, max_agents, expires_at)
+   * Returns current license data
    */
   getLicenseInfo() {
     return this._licenseData;
@@ -149,4 +140,10 @@ class NullBridge {
   }
 }
 
-module.exports = { NullBridge, SDK_VERSION };
+module.exports = {
+  NullBridge,
+  SDK_VERSION,
+  NullBridgeLicenseError,
+  NullBridgeApiError,
+  NullBridgeCredentialError,
+};

package/src/license.js

@@ -1,16 +1,21 @@
 'use strict';
 
+const { NullBridgeLicenseError } = require('./errors');
+
+/**
+ * LicenseClient — validates and monitors NullBridge license keys
+ */
 class LicenseClient {
   constructor(config, http) {
-    this._config   = config;
-    this._http     = http;
-    this._watcher  = null;
-    this._data     = null;
+    this._config      = config;
+    this._http        = http;
+    this._watcherTimer = null;
   }
 
   /**
-   * Validate license against NullBridge license server.
-   * Throws if license is invalid, expired, suspended, or cancelled.
+   * Validate the license key against the license server
+   * @returns {Promise<object>} license data
+   * @throws {NullBridgeLicenseError} if license is invalid or expired
    */
   async validate() {
     try {
@@ -21,80 +26,66 @@ class LicenseClient {
       );
 
       if (status === 200 && body.valid) {
-        this._data = body;
-        return body;
+        return {
+          valid:      true,
+          customer:   body.customer,
+          company:    body.company,
+          plan:       body.plan,
+          maxAgents:  body.max_agents,
+          expiresAt:  body.expires_at,
+          reason:     body.reason,
+        };
       }
 
-      // License exists but is not valid
-      const reason = body.reason || 'UNKNOWN';
-      const msg    = body.message || 'License validation failed.';
-
-      const errors = {
-        SUSPENDED:    `License suspended. Contact brian@nullbridge.ai to restore service.`,
-        CANCELLED:    `License cancelled. Contact brian@nullbridge.ai.`,
-        EXPIRED:      `License expired. Contact brian@nullbridge.ai to renew.`,
-        NOT_FOUND:    `License key not found. Verify your NULLBRIDGE_LICENSE_KEY is correct.`,
-        GRACE_PERIOD: null, // still valid — handled below
-      };
+      // License server reachable but license invalid
+      const reason  = body.reason  || 'INVALID';
+      const message = body.message || 'Invalid or expired license key.';
 
-      if (reason === 'GRACE_PERIOD') {
-        console.warn(`[NullBridge] Warning: ${msg}`);
-        this._data = body;
-        return body;
-      }
-
-      throw new Error(`[NullBridge] ${errors[reason] || msg}`);
+      throw new NullBridgeLicenseError(reason,
+        `${message} Contact brian@nullbridge.ai to renew or obtain a license key.`
+      );
 
     } catch (err) {
-      if (err.message.startsWith('[NullBridge]')) throw err;
-
-      // Network error — allow startup but warn
-      console.warn(`[NullBridge] License server unreachable (${err.message}). Allowing startup — will retry in 24 hours.`);
-      return null;
+      if (err instanceof NullBridgeLicenseError) throw err;
+
+      // Network error — fail open with a warning
+      console.warn('[NullBridge] License server unreachable — continuing in offline mode.');
+      return {
+        valid:    true,
+        reason:   'SERVER_UNREACHABLE',
+        offline:  true,
+        customer: 'Unknown',
+        plan:     'unknown',
+      };
     }
   }
 
   /**
-   * Start periodic license checks.
-   * @param {function} onInvalid - callback(valid, reason) when license becomes invalid
+   * Start periodic license re-validation
+   * @param {function} onStatusChange - called with (valid, reason) when status changes
    */
-  startWatcher(onInvalid) {
-    if (this._watcher) return;
-
-    this._watcher = setInterval(async () => {
+  startWatcher(onStatusChange) {
+    if (this._watcherTimer) return;
+    this._watcherTimer = setInterval(async () => {
       try {
-        const { status, body } = await this._http.post(
-          this._config.serverUrl,
-          '/api/validate',
-          { key: this._config.licenseKey }
-        );
-
-        if (status !== 200 || !body.valid) {
-          if (body.reason !== 'GRACE_PERIOD') {
-            onInvalid(false, body.reason || 'UNKNOWN');
-          } else {
-            console.warn(`[NullBridge] License check: grace period — payment overdue.`);
-          }
-        }
+        const result = await this.validate();
+        if (!result.valid) onStatusChange(false, result.reason);
       } catch (err) {
-        console.warn(`[NullBridge] License check: server unreachable. Will retry in 24 hours.`);
+        if (err instanceof NullBridgeLicenseError) {
+          onStatusChange(false, err.reason);
+        }
       }
     }, this._config.checkInterval);
 
-    // Don't let the watcher keep the process alive
-    if (this._watcher.unref) this._watcher.unref();
+    if (this._watcherTimer.unref) this._watcherTimer.unref();
   }
 
   stopWatcher() {
-    if (this._watcher) {
-      clearInterval(this._watcher);
-      this._watcher = null;
+    if (this._watcherTimer) {
+      clearInterval(this._watcherTimer);
+      this._watcherTimer = null;
     }
   }
-
-  getData() {
-    return this._data;
-  }
 }
 
 module.exports = { LicenseClient };