> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nullbridge.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Reference

> Complete reference for the @nullbridge/sdk package

## Installation

```bash theme={null}
npm install @nullbridge/sdk
```

**Requirements:** Node.js 18+, ESM or CommonJS

***

## NullBridge class

### Constructor

```js theme={null}
import pkg from '@nullbridge/sdk';
const { NullBridge } = pkg;

const nb = new NullBridge(config);
```

| Parameter       | Type      | Required | Description                                         |
| --------------- | --------- | -------- | --------------------------------------------------- |
| `licenseKey`    | `string`  | Yes      | Your NullBridge license key                         |
| `apiUrl`        | `string`  | No       | API base URL (default: `https://api.nullbridge.ai`) |
| `serverUrl`     | `string`  | No       | License server URL                                  |
| `skipLicense`   | `boolean` | No       | Skip license check for local dev                    |
| `autoShutdown`  | `boolean` | No       | Auto-exit if license is revoked (default: `true`)   |
| `checkInterval` | `number`  | No       | License recheck interval in ms (default: 24h)       |
| `debug`         | `boolean` | No       | Enable verbose logging                              |

***

### `nb.init()`

Validates the license and starts background services. Call once on application startup.

```js theme={null}
await nb.init();
```

**Throws:** `NullBridgeLicenseError` if the license is invalid or expired.

***

### `nb.shutdown()`

Gracefully shuts down — flushes logs, stops heartbeats and license watchers.

```js theme={null}
await nb.shutdown();
```

***

### `nb.getLicenseInfo()`

Returns the current license data.

```js theme={null}
const info = nb.getLicenseInfo();
// { customer: 'Acme Corp', plan: 'starter', ... }
```

***

### `nb.getVersion()`

Returns the SDK version string.

```js theme={null}
nb.getVersion(); // '1.0.5'
```

***

## nb.agents

### `nb.agents.register(agent)`

Registers an AI agent with NullBridge. The agent will appear in the Agent Registry and SIEM events will be logged.

```js theme={null}
const agent = await nb.agents.register({
  id: 'my-agent-001',
  name: 'MyAgent',
  type: 'automation',
  scopes: ['read:tasks', 'write:reports'],
  metadata: {
    owner_email: 'you@company.com',
    team: 'Engineering',
    environment: 'prod',
  },
});
```

**Parameters:**

| Field                  | Type       | Required | Description                                    |
| ---------------------- | ---------- | -------- | ---------------------------------------------- |
| `id`                   | `string`   | Yes      | Unique agent identifier                        |
| `name`                 | `string`   | Yes      | Display name shown in dashboard                |
| `type`                 | `string`   | Yes      | Agent type (e.g. `automation`, `orchestrator`) |
| `scopes`               | `string[]` | No       | Minimum required permission scopes             |
| `metadata.owner_email` | `string`   | No       | Owner email address                            |
| `metadata.team`        | `string`   | No       | Team name                                      |
| `metadata.environment` | `string`   | No       | `dev`, `staging`, or `prod`                    |

**Returns:** Agent object with `id`, `name`, `status`, and registration details.

<Note>
  If an agent with the same `id` already exists, it will be updated rather than duplicated.
</Note>

***

## Available scopes

| Scope             | Description           |
| ----------------- | --------------------- |
| `read:claims`     | Read identity claims  |
| `write:claims`    | Write identity claims |
| `read:policy`     | Read policies         |
| `write:policy`    | Write policies        |
| `invoke:workflow` | Trigger workflows     |
| `read:customers`  | Read customer data    |
| `write:customers` | Write customer data   |
| `read:repos`      | Read repositories     |
| `write:reports`   | Write reports         |
| `read:tasks`      | Read tasks            |
| `write:tasks`     | Write tasks           |
| `read:database`   | Read database         |
| `admin:infra`     | Infrastructure admin  |
| `read:secrets`    | Read secrets          |
| `invoke:deploy`   | Trigger deployments   |
| `read:audit`      | Read audit logs       |

***

## Agent tiers

Agents are automatically assigned a tier based on their scopes and risk profile:

| Tier | Label        | Credential    | Max TTL |
| ---- | ------------ | ------------- | ------- |
| T1   | Stateless    | OAuth2 JWT    | 900s    |
| T2   | Task-Scoped  | SPIFFE/SVID   | 1800s   |
| T3   | Orchestrator | Vault Dynamic | 3600s   |
| T4   | Privileged   | PAM JIT       | 7200s   |
| T5   | Sub-Agent    | Child Token   | 600s    |

***

## Error types

```js theme={null}
import pkg from '@nullbridge/sdk';
const { NullBridgeLicenseError, NullBridgeApiError, NullBridgeCredentialError } = pkg;
```

| Error                       | Thrown when                             |
| --------------------------- | --------------------------------------- |
| `NullBridgeLicenseError`    | License is invalid, expired, or missing |
| `NullBridgeApiError`        | API request fails                       |
| `NullBridgeCredentialError` | Credential operation fails              |

```js theme={null}
try {
  await nb.init();
} catch (err) {
  if (err instanceof NullBridgeLicenseError) {
    console.error('License issue:', err.message);
  }
}
```

***

## CommonJS usage

```js theme={null}
const { NullBridge } = require('@nullbridge/sdk');

async function main() {
  const nb = new NullBridge({ licenseKey: process.env.NULLBRIDGE_LICENSE_KEY });
  await nb.init();
  await nb.agents.register({ id: 'agent-001', name: 'MyAgent', type: 'automation' });
  await nb.shutdown();
}

main().catch(console.error);
```