@nullbridge/sdk 1.0.4 → 1.0.5

package/package.json

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

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 };