import { botpartyFetch } from '@botparty/sdk';

// That's it. First call auto-registers a namespace and generates a keypair.
const res = await botpartyFetch('https://api.example.com/data');
const data = await res.json();

On first run, the SDK:

Generates an Ed25519 keypair
Registers a namespace like brave-fox-a3f2 on the BotParty server
Stores the identity in ~/.botparty/

On every call, it:

Checks if the key is about to go stale → auto-rotates
Signs a JWT with the namespace identity
Sends the request with Authorization: Bearer <jwt>

Error Handling

BotParty-compatible servers return typed errors that the SDK catches and throws as specific error classes. Each error has a code, message, and optional actionUrl for human intervention.

import {
  botpartyFetch,
  NamespaceLockedError,
  PaymentRequiredError,
  InsufficientPermissionError,
  LinkRequiredError,
} from '@botparty/sdk';

try {
  const res = await botpartyFetch('https://api.example.com/data');
} catch (err) {
  if (err instanceof NamespaceLockedError) {
    console.log('Namespace locked! Human must unlock at:', err.actionUrl);
  }
  if (err instanceof PaymentRequiredError) {
    console.log('Payment needed:', err.message, err.actionUrl);
  }
  if (err instanceof InsufficientPermissionError) {
    console.log('Missing scopes:', err.missingScopes);
  }
  if (err instanceof LinkRequiredError) {
    console.log('Link a human account at:', err.actionUrl);
  }
}

Advanced Usage

Use BotPartyClient for full control over registration, key management, and namespace operations.

import { BotPartyClient } from '@botparty/sdk';

const client = new BotPartyClient({
  serverUrl: 'https://id.botparty.club',  // default
  algorithm: 'EdDSA',                  // default (also supports ES256)
  rotationTTL: 15,                     // minutes, default
});

// Register with a custom name
await client.register('my-cool-bot', 'My Cool Bot');

// Or let it auto-register
await client.ensureRegistered();

// Generate a JWT token (handles registration + rotation automatically)
const token = await client.generateToken();

// Authenticated fetch
const res = await client.fetch('https://api.example.com/data');

// Check identity
const me = client.whoami();
// { namespace: 'my-cool-bot', keyId: 'key_...', staleAt: '...', ... }

Key Management

// List all keys
const keys = await client.keys.list();

// Add a delegated key
await client.keys.add({
  publicKey: '-----BEGIN PUBLIC KEY-----\n...',
  scopes: ['mongo://production/*:read'],
  rotationTTL: 60,
});

// Rotate the current machine's key
await client.keys.rotateCurrent();

// Fluent key operations
const key = client.key('key_abc123');
await key.info();
await key.update({ label: 'Updated label' });
await key.invalidate('Suspected compromise');
await key.delete();

Namespace Operations

// Get namespace info from server
const info = await client.info();
// { namespace: '...', status: 'active', linked: true, activeKeys: 2, ... }

// Generate a link URL for a human to claim ownership
const { url } = await client.link();
console.log('Share this with your human:', url);

// Destroy namespace (irreversible)
await client.destroy();

// Clear local state only
client.reset();

Configuration

Option	Env Variable	Default	Description
`serverUrl`	`BOTPARTY_SERVER_URL`	`https://id.botparty.club`	BotParty server URL
`stateDir`	`BOTPARTY_STATE_DIR`	`~/.botparty`	Local state directory
`algorithm`	—	`EdDSA`	Key algorithm (`EdDSA` or `ES256`)
`rotationTTL`	—	`15`	Key rotation TTL in minutes

State Files

The SDK stores identity and keys in ~/.botparty/:

~/.botparty/
├── identity.json    # namespace, keyId, algorithm, rotatedAt, etc.
└── private.pem      # Ed25519/EC private key (mode 0600)

Error Classes

Class	Code	HTTP	Description
`BotPartyError`	varies	varies	Base error class
`NamespaceLockedError`	`NAMESPACE_LOCKED`	423	Namespace locked, human must unlock
`PaymentRequiredError`	`PAYMENT_REQUIRED`	402	Payment needed for this action
`InsufficientPermissionError`	`INSUFFICIENT_PERMISSION`	403	Missing required scopes
`LinkRequiredError`	`LINK_REQUIRED`	403	Must link a human account