@nullbridge/sdk 1.0.1 → 1.0.3

package/README.md

@@ -12,12 +12,14 @@ NullBridge gives your AI agents a cryptographic identity, secure credential vaul
 npm install @nullbridge/sdk
 ```
 
+Requires Node.js 18+.
+
 ---
 
 ## Quick Start
 
 ```js
-const { NullBridge } = require('@nullbridge/sdk');
+import { NullBridge } from '@nullbridge/sdk';
 
 const nb = new NullBridge({
   licenseKey: process.env.NULLBRIDGE_LICENSE_KEY,
@@ -26,35 +28,22 @@ const nb = new NullBridge({
 await nb.init();
 
 const agent = await nb.agents.register({
-  name:   'claims-processor',
+  id:     'claims-processor-001',   // unique identifier for this agent
+  name:   'Claims Processor',
   type:   'llm',
   model:  'gpt-4o',
   scopes: ['read:claims', 'write:reports'],
 });
-```
-
-That's it. NullBridge validates your license on startup, registers your agent with a cryptographic identity, and begins monitoring automatically.
-
----
 
-## Configuration
+// Log every action your agent takes
+await agent.logAction('process_claim', { claimId: 'CLM-001', outcome: 'approved' });
 
-```js
-const nb = new NullBridge({
-  licenseKey:    process.env.NULLBRIDGE_LICENSE_KEY, // required
-  serverUrl:     'https://nullbridge-license-server-production.up.railway.app', // default
-  apiUrl:        'https://api.nullbridge.ai',        // default
-  skipLicense:   false,   // set true for local development only
-  autoShutdown:  true,    // shut down process if license is revoked
-  checkInterval: 86400000, // license check interval in ms (default: 24 hours)
-  debug:         false,   // enable verbose logging
-  siem: {
-    endpoint: 'https://your-siem.com/ingest', // optional
-    format:   'json', // 'json' | 'cef' | 'leef'
-  },
-});
+// Graceful shutdown
+await nb.shutdown();
 ```
 
+That's it. NullBridge validates your license on startup, registers your agent with a cryptographic identity, and begins monitoring automatically. Every action appears in your NullBridge dashboard in real time.
+
 ---
 
 ## Environment Variables
@@ -63,15 +52,30 @@ const nb = new NullBridge({
 NULLBRIDGE_LICENSE_KEY=NB-XXXX-XXXX-XXXX-XXXX
 ```
 
-Contact brian@nullbridge.ai to obtain a license key.
+Contact [brian@nullbridge.ai](mailto:brian@nullbridge.ai) to obtain a license key.
+
+---
+
+## Configuration
+
+```js
+const nb = new NullBridge({
+  licenseKey:    process.env.NULLBRIDGE_LICENSE_KEY, // required
+  apiUrl:        'https://api.nullbridge.ai',         // default
+  skipLicense:   false,    // set true for local dev only
+  autoShutdown:  true,     // shut down process if license is revoked
+  checkInterval: 86400000, // license recheck interval in ms (default: 24h)
+  debug:         false,    // enable verbose logging
+});
+```
 
 ---
 
 ## API Reference
 
 ### `nb.init()`
-Initialize NullBridge. Call once on application startup before serving traffic.
-Validates license and starts background services.
+
+Initialize NullBridge. Call once on application startup before serving traffic. Validates your license key and starts background services.
 
 ```js
 await nb.init();
@@ -82,41 +86,106 @@ await nb.init();
 ### `nb.agents`
 
 #### `nb.agents.register(options)`
-Register an AI agent with NullBridge.
+
+Register an AI agent with NullBridge. The agent appears immediately in your NullBridge dashboard under Agent Registry.
 
 ```js
 const agent = await nb.agents.register({
-  name:   'fraud-detector',    // required — human readable name
-  type:   'llm',               // required — 'llm' | 'rpa' | 'workflow' | 'custom'
-  model:  'claude-3-5-sonnet', // optional
+  id:     'fraud-detector-001',  // required — unique, stable identifier
+  name:   'Fraud Detector',      // required — display name
+  type:   'llm',                 // required — 'llm' | 'rpa' | 'workflow' | 'custom'
+  model:  'claude-3-5-sonnet',   // optional
   scopes: ['read:transactions', 'write:alerts'], // optional
-  metadata: { team: 'risk' },  // optional
+  metadata: {
+    team:        'risk',
+    environment: 'prod',
+    owner_email: 'team@company.com',
+  },
 });
 ```
 
-#### `agent.logAction(action, details)`
-Log an action this agent performed.
+Returns an agent instance with the following methods:
+
+#### `agent.logAction(action, details?)`
+
+Log an action this agent performed. Appears in the audit trail.
 
 ```js
-await agent.logAction('analyze_transaction', { txId: 'TX-1234', amount: 5000 });
+await agent.logAction('analyze_transaction', {
+  txId:   'TX-1234',
+  amount: 5000,
+  result: 'approved',
+});
 ```
 
 #### `agent.hasScope(scope)`
-Check if agent has a specific permission.
+
+Check if the agent has a specific permission scope.
 
 ```js
-if (!agent.hasScope('write:alerts')) throw new Error('Not authorized');
+if (!agent.hasScope('write:alerts')) {
+  throw new Error('Agent not authorized for this action');
+}
 ```
 
 #### `agent.deregister()`
-Deregister agent and revoke its identity.
+
+Deregister the agent and revoke its identity. The agent status updates to `deprovisioned` in the dashboard.
+
+```js
+await agent.deregister();
+```
+
+---
+
+### `nb.audit`
+
+#### `nb.audit.log(event)`
+
+Log an agent action to the audit trail. Supports fire-and-forget (no await required for non-critical logging).
+
+```js
+await nb.audit.log({
+  agentId:    agent.id,           // required
+  agentName:  agent.name,         // recommended
+  action:     'process_claim',    // required
+  resource:   'claim:CLM-001',    // optional
+  outcome:    'success',          // 'success' | 'failure' | 'blocked'
+  details:    { amount: 15000 },  // optional
+  ip:         req.ip,             // optional
+  duration_ms: 1240,              // optional
+});
+```
+
+#### `nb.audit.batch(events)`
+
+Log multiple events in a single request. More efficient for high-throughput agents.
+
+```js
+await nb.audit.batch([
+  { agentId: agent.id, agentName: agent.name, action: 'read_record',   outcome: 'success' },
+  { agentId: agent.id, agentName: agent.name, action: 'write_report',  outcome: 'success' },
+  { agentId: agent.id, agentName: agent.name, action: 'delete_record', outcome: 'blocked' },
+]);
+```
+
+#### `nb.audit.logViolation(agentId, agentName, action, reason)`
+
+Log a policy violation. Outcome is automatically set to `blocked` and triggers a SIEM alert.
+
+```js
+await nb.audit.logViolation(agent.id, agent.name, 'delete_record', 'scope_denied');
+```
 
 ---
 
 ### `nb.credentials`
 
+NullBridge tracks credential lifecycle metadata — store, rotate, and revoke events are logged to your audit trail and SIEM automatically.
+
 #### `nb.credentials.store(options)`
-Store a credential securely (AES-256-GCM encrypted).
+
+Register a credential and log it to the audit trail.
 
 ```js
 const credId = await nb.credentials.store({
@@ -124,52 +193,24 @@ const credId = await nb.credentials.store({
   name:    'openai-api-key',
   value:   process.env.OPENAI_API_KEY,
   type:    'api_key', // 'api_key' | 'oauth_token' | 'password' | 'certificate'
-  ttl:     86400,     // optional: expire after 24 hours
+  ttl:     86400,     // optional: seconds until expiry
 });
 ```
 
-#### `nb.credentials.get(credId)`
-Retrieve a credential value.
+#### `nb.credentials.rotate(credId, newValue?)`
 
-```js
-const apiKey = await nb.credentials.get(credId);
-```
-
-#### `nb.credentials.rotate(credId, newValue)`
-Rotate a credential and log the rotation in audit trail.
+Log a credential rotation event.
 
 ```js
 await nb.credentials.rotate(credId, newApiKey);
 ```
 
 #### `nb.credentials.revoke(credId)`
-Permanently revoke a credential.
-
----
 
-### `nb.audit`
-
-#### `nb.audit.log(event)`
-Log an agent action to the audit trail.
-
-```js
-nb.audit.log({
-  agentId:   agent.id,
-  agentName: agent.name,
-  action:    'process_claim',         // required
-  resource:  'claim:CLM-20240001',    // optional
-  outcome:   'success',               // 'success' | 'failure' | 'blocked'
-  details:   { amount: 15000 },       // optional
-  ip:        req.ip,                  // optional
-  duration:  1240,                    // optional: ms
-});
-```
-
-#### `nb.audit.logViolation(agentId, agentName, action, reason)`
-Log a policy violation (outcome is automatically set to 'blocked').
+Permanently revoke a credential and log the revocation.
 
 ```js
-nb.audit.logViolation(agent.id, agent.name, 'delete_record', 'scope_denied');
+await nb.credentials.revoke(credId);
 ```
 
 ---
@@ -177,7 +218,8 @@ nb.audit.logViolation(agent.id, agent.name, 'delete_record', 'scope_denied');
 ### `nb.anomaly`
 
 #### `nb.anomaly.record(agentId, metric, value)`
-Record a behavioral metric. NullBridge builds a statistical baseline and alerts on deviations.
+
+Record a behavioral metric. NullBridge builds a statistical baseline and fires an alert when a value deviates significantly (z-score threshold configurable in dashboard).
 
 ```js
 nb.anomaly.record(agent.id, 'api_calls_per_minute', 14);
@@ -186,27 +228,30 @@ nb.anomaly.record(agent.id, 'unique_endpoints',     3);
 ```
 
 #### `nb.anomaly.onAlert(handler)`
-Register a callback for anomaly alerts.
+
+Register a callback that fires when an anomaly is detected.
 
 ```js
 nb.anomaly.onAlert(alert => {
-  console.error(`Anomaly: ${alert.agentId} — ${alert.metric} (z=${alert.zScore})`);
-  // Send to PagerDuty, Slack, etc.
+  console.error(`Anomaly detected: ${alert.agentId} — ${alert.metric} (z=${alert.zScore})`);
+  // Forward to PagerDuty, Slack, OpsGenie, etc.
 });
 ```
 
 #### `nb.anomaly.check(agentId, metric, value)`
+
 Check if a value is anomalous without recording it.
 
 ```js
 const { anomalous, zScore } = nb.anomaly.check(agent.id, 'api_calls', 500);
-if (anomalous) console.warn('Unusual API call volume');
+if (anomalous) console.warn(`Unusual API call volume — z-score: ${zScore}`);
 ```
 
 ---
 
 ### `nb.shutdown()`
-Gracefully shut down — flushes audit logs and stops background services.
+
+Gracefully shut down NullBridge — flushes pending audit logs and stops background services. Call before `process.exit()`.
 
 ```js
 process.on('SIGTERM', async () => {
@@ -217,16 +262,87 @@ process.on('SIGTERM', async () => {
 
 ---
 
+## Full Example
+
+```js
+import { NullBridge } from '@nullbridge/sdk';
+
+const nb = new NullBridge({
+  licenseKey: process.env.NULLBRIDGE_LICENSE_KEY,
+  debug: false,
+});
+
+await nb.init();
+
+// Register your agent once on startup
+const agent = await nb.agents.register({
+  id:     'invoice-processor-001',
+  name:   'Invoice Processor',
+  type:   'llm',
+  model:  'gpt-4o',
+  scopes: ['read:invoices', 'write:payments'],
+  metadata: { team: 'finance', environment: 'prod' },
+});
+
+// Store credentials securely
+const credId = await nb.credentials.store({
+  agentId: agent.id,
+  name:    'stripe-api-key',
+  value:   process.env.STRIPE_SECRET_KEY,
+  type:    'api_key',
+});
+
+// Monitor behavior
+nb.anomaly.onAlert(alert => {
+  console.error(`[NullBridge] Anomaly: ${alert.metric} — z=${alert.zScore}`);
+});
+
+// Log every action
+async function processInvoice(invoiceId) {
+  if (!agent.hasScope('write:payments')) {
+    await nb.audit.logViolation(agent.id, agent.name, 'process_payment', 'scope_denied');
+    throw new Error('Unauthorized');
+  }
+
+  // ... your agent logic ...
+
+  await agent.logAction('process_invoice', { invoiceId, outcome: 'success' });
+  nb.anomaly.record(agent.id, 'invoices_per_hour', 1);
+}
+
+// Graceful shutdown
+process.on('SIGTERM', async () => {
+  await nb.shutdown();
+  process.exit(0);
+});
+```
+
+---
+
+## Dashboard
+
+All agent activity flows into your NullBridge dashboard at [app.nullbridge.ai](https://app.nullbridge.ai):
+
+- **Agent Registry** — all registered agents, their status, tier, and risk score
+- **Audit Trail** — every action logged with full context
+- **SIEM Events** — policy violations, anomalies, and credential events
+- **Anomaly Detection** — behavioral baselines and z-score alerts
+
+---
+
+## Support
+
+- Email: [brian@nullbridge.ai](mailto:brian@nullbridge.ai)
+- Website: [nullbridge.ai](https://nullbridge.ai)
+
+---
+
 ## License
 
 This software is proprietary and confidential. Use requires a valid NullBridge license key.
-Contact brian@nullbridge.ai for licensing.
 
 **NullBridge Technologies**
-brian@nullbridge.ai | nullbridge.ai
 
 ---
 
-CONFIDENTIALITY & IP NOTICE: This software and documentation contain proprietary and confidential
-information belonging to NullBridge Technologies. Protected under applicable intellectual property
-laws. Unauthorized use, disclosure, or distribution is strictly prohibited.
+*CONFIDENTIALITY & IP NOTICE: This software and documentation contain proprietary and confidential information belonging to NullBridge Technologies. Protected under applicable intellectual property laws. Unauthorized use, disclosure, or distribution is strictly prohibited.*

package/package.json

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