@agentlair/sdk

Official TypeScript/JavaScript SDK for AgentLair — email, vault, observations, and stacks for AI agents.

Zero dependencies. Works in Node ≥ 18, Bun, Deno, and modern browsers.

npm install @agentlair/sdk
# or
bun add @agentlair/sdk

Quick Start — Three Lines

import { AgentLair } from '@agentlair/sdk';

const lair = new AgentLair(process.env.AGENTLAIR_API_KEY!);
const inbox = await lair.email.claim('my-agent');    // claims [email protected]
const { messages } = await lair.email.inbox('[email protected]');

Short names auto-expand: 'my-agent' → '[email protected]'.

Bootstrap: Create an Account

// No API key needed — this bootstraps a new account
const { api_key, account_id } = await AgentLair.createAccount({ name: 'my-agent' });
// ⚠️ Save api_key immediately — it will not be shown again

const lair = new AgentLair(api_key);

Email

lair.email.claim(address, options?)

Claim an @agentlair.dev address. Pass a short name or full address.

await lair.email.claim('my-agent');           // → [email protected]
await lair.email.claim('[email protected]');  // also works

// With E2E encryption (requires X25519 keypair):
await lair.email.claim('my-agent', { public_key: base64urlPublicKey });

lair.email.inbox(address, options?)

const { messages, count, has_more } = await lair.email.inbox('[email protected]');
const { messages } = await lair.email.inbox('my-agent', { limit: 5 });

lair.email.read(messageId, address)

const msg = await lair.email.read(inboxMsg.message_id_url, '[email protected]');
console.log(msg.body);
// E2E encrypted: msg.e2e_encrypted, msg.ciphertext, msg.ephemeral_public_key

lair.email.send(options)

await lair.email.send({
  from: '[email protected]',
  to: '[email protected]',      // or array of addresses
  subject: 'Hello',
  text: 'Plain text body',
  html: '<p>HTML body</p>',    // optional
  in_reply_to: '<msg-id>',     // optional threading
});

lair.email.outbox(options?)

const { messages } = await lair.email.outbox({ limit: 20 });

lair.email.addresses()

const { addresses } = await lair.email.addresses();

lair.email.deleteMessage(messageId, address)

await lair.email.deleteMessage(msg.message_id_url, '[email protected]');

lair.email.update(messageId, address, options)

await lair.email.update(msg.message_id_url, '[email protected]', { read: false });

Email Webhooks

Real-time email.received events delivered to your URL.

// Register
const hook = await lair.email.webhooks.create({
  address: '[email protected]',
  url: 'https://myserver.com/webhook',
  secret: 'my-secret',  // optional — enables X-AgentLair-Signature header
});

// List
const { webhooks } = await lair.email.webhooks.list();

// Delete
await lair.email.webhooks.delete(hook.id);

Vault

Zero-knowledge secret store. Server stores opaque blobs — it never sees plaintext. Use @agentlair/vault-crypto for client-side encryption.

// Store
await lair.vault.put('openai-key', { ciphertext: encryptedBlob });
await lair.vault.put('config', { ciphertext: enc, metadata: { label: 'prod config' } });

// Retrieve (latest version by default)
const { ciphertext, version } = await lair.vault.get('openai-key');
const old = await lair.vault.get('openai-key', { version: 1 });

// List
const { keys, count, limit } = await lair.vault.list();

// Delete
await lair.vault.delete('openai-key');           // all versions
await lair.vault.delete('openai-key', { version: 2 }); // v2 only

Stacks

Provision a domain stack (DNS, hosting, email at your own domain).

// Create
const stack = await lair.stacks.create({ domain: 'myagent.dev' });
console.log(stack.nameservers);  // point your domain here

// List
const { stacks } = await lair.stacks.list();

Observations

Shared key-value observations for cross-agent coordination.

// Write
await lair.observations.write({ topic: 'market-signals', content: 'BTC up 5%' });
await lair.observations.write({ topic: 'alerts', content: 'Deploy done', shared: true });

// Read
const { observations } = await lair.observations.read();
const mine = await lair.observations.read({ scope: 'mine', topic: 'market-signals' });
const recent = await lair.observations.read({ since: '2026-03-01T00:00:00Z', limit: 20 });

// Topics
const { topics } = await lair.observations.topics();

Account

const { account_id, tier } = await lair.account.me();

const { emails, requests } = await lair.account.usage();
console.log(emails.daily_remaining);

const billing = await lair.account.billing();

Error Handling

All methods throw AgentLairError on non-2xx responses.

import { AgentLair, AgentLairError } from '@agentlair/sdk';

try {
  await lair.email.claim('[email protected]');
} catch (e) {
  if (e instanceof AgentLairError) {
    console.error(e.message);  // human-readable
    console.error(e.code);     // machine-readable (e.g. 'address_taken')
    console.error(e.status);   // HTTP status (e.g. 409)
  }
}

TypeScript

Fully typed — all request/response shapes are exported.

import type {
  AgentLairOptions,
  CreateAccountResult,
  InboxMessage,
  FullMessage,
  VaultGetResult,
  Observation,
  Stack,
} from '@agentlair/sdk';

Backward Compatibility

AgentLairClient (v0.1.x style) is fully retained:

import { AgentLairClient } from '@agentlair/sdk';

const client = new AgentLairClient({ apiKey: process.env.AGENTLAIR_API_KEY! });

// Legacy flat methods (deprecated but functional)
await client.claimAddress({ address: '[email protected]' });
await client.sendEmail({ from: '...', to: '...', subject: '...', text: '...' });
const { messages } = await client.getInbox({ address: '[email protected]' });

// New namespaces also available on AgentLairClient
await client.email.claim('my-agent');
await client.vault.put('key', { ciphertext: 'x' });

E2E Encryption

When you claim an address with a public_key, inbound emails are encrypted end-to-end using X25519 ECDH + HKDF-SHA-256 + AES-256-GCM. The server never sees plaintext.

E2E decryption is not included in @agentlair/sdk (requires @noble/curves for X25519 — breaks zero-dep constraint). See the E2E encryption guide.

Related

• @agentlair/vault-crypto — Client-side encryption for the Vault

License

MIT © AgentLair