@agentlair/sdk 0.1.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @agentlair/sdk
 
-Official TypeScript/JavaScript SDK for [AgentLair](https://agentlair.dev) — email, vault, and account management for AI agents.
+Official TypeScript/JavaScript SDK for [AgentLair](https://agentlair.dev) — email, vault, observations, and stacks for AI agents.
 
 **Zero dependencies. Works in Node ≥ 18, Bun, Deno, and modern browsers.**
 
@@ -12,153 +12,189 @@ bun add @agentlair/sdk
 
 ---
 
-## Quick Start
+## Quick Start — Three Lines
 
 ```typescript
-import { AgentLairClient } from '@agentlair/sdk';
+import { AgentLair } from '@agentlair/sdk';
 
-// 1. Create an account (no existing key needed)
-const { api_key, account_id } = await AgentLairClient.createAccount({ name: 'my-agent' });
-// ⚠️ Save api_key immediately — it will not be shown again
+const lair = new AgentLair(process.env.AGENTLAIR_API_KEY!);
+const inbox = await lair.email.claim('my-agent');    // claims my-agent@agentlair.dev
+const { messages } = await lair.email.inbox('my-agent@agentlair.dev');
+```
 
-// 2. Instantiate the client
-const client = new AgentLairClient({ apiKey: api_key });
+Short names auto-expand: `'my-agent'` → `'my-agent@agentlair.dev'`.
 
-// 3. Claim an email address
-await client.claimAddress({ address: 'my-agent@agentlair.dev' });
+---
 
-// 4. Send email
-await client.sendEmail({
-  from: 'my-agent@agentlair.dev',
-  to: 'user@example.com',
-  subject: 'Hello from AgentLair',
-  text: 'Hi! This message was sent by an AI agent.',
-});
+## Bootstrap: Create an Account
 
-// 5. Read inbox
-const { messages } = await client.getInbox({ address: 'my-agent@agentlair.dev' });
-for (const msg of messages) {
-  console.log(msg.from, msg.subject, msg.snippet);
-  const full = await client.readMessage({
-    messageId: msg.message_id_url,
-    address: 'my-agent@agentlair.dev',
-  });
-  console.log(full.body);
-}
+```typescript
+// 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);
 ```
 
 ---
 
-## Account
+## Email
 
-### `AgentLairClient.createAccount(options?)` — static
+### `lair.email.claim(address, options?)`
 
-Create a new account and get an API key. No existing account needed.
+Claim an `@agentlair.dev` address. Pass a short name or full address.
 
 ```typescript
-const { api_key, account_id, tier, limits } = await AgentLairClient.createAccount({
-  name: 'my-agent',   // optional display name
-  email: 'me@example.com', // optional recovery email (enables dashboard login)
-});
-```
-
-Returns `CreateAccountResult`. **The `api_key` is shown only once — store it immediately.**
+await lair.email.claim('my-agent');           // → my-agent@agentlair.dev
+await lair.email.claim('my-agent@agentlair.dev');  // also works
 
----
+// With E2E encryption (requires X25519 keypair):
+await lair.email.claim('my-agent', { public_key: base64urlPublicKey });
+```
 
-## Email
+### `lair.email.inbox(address, options?)`
 
-### `client.claimAddress(options)`
+```typescript
+const { messages, count, has_more } = await lair.email.inbox('my-agent@agentlair.dev');
+const { messages } = await lair.email.inbox('my-agent', { limit: 5 });
+```
 
-Claim an `@agentlair.dev` address. First-touch ownership — first to claim it owns it.
+### `lair.email.read(messageId, address)`
 
 ```typescript
-await client.claimAddress({ address: 'my-agent@agentlair.dev' });
-
-// With E2E encryption (optional — requires X25519 keypair):
-await client.claimAddress({
-  address: 'my-agent@agentlair.dev',
-  public_key: base64urlPublicKey, // 32-byte X25519 public key
-});
+const msg = await lair.email.read(inboxMsg.message_id_url, 'my-agent@agentlair.dev');
+console.log(msg.body);
+// E2E encrypted: msg.e2e_encrypted, msg.ciphertext, msg.ephemeral_public_key
 ```
 
-### `client.sendEmail(options)`
-
-Send a DKIM-signed email from an address you own. Supports threading.
+### `lair.email.send(options)`
 
 ```typescript
-await client.sendEmail({
+await lair.email.send({
   from: 'my-agent@agentlair.dev',
   to: 'user@example.com',      // or array of addresses
   subject: 'Hello',
   text: 'Plain text body',
-  html: '<p>HTML body</p>',    // optional; send text or html or both
+  html: '<p>HTML body</p>',    // optional
   in_reply_to: '<msg-id>',     // optional threading
 });
 ```
 
-### `client.getInbox(options)`
+### `lair.email.outbox(options?)`
 
-Get inbox messages (preview only — no full body).
+```typescript
+const { messages } = await lair.email.outbox({ limit: 20 });
+```
+
+### `lair.email.addresses()`
 
 ```typescript
-const { messages, count, has_more } = await client.getInbox({
-  address: 'my-agent@agentlair.dev',
-  limit: 20,  // default: 20, max: 100
-});
+const { addresses } = await lair.email.addresses();
 ```
 
-### `client.readMessage(options)`
+### `lair.email.deleteMessage(messageId, address)`
 
-Read the full body of a message. Marks as read.
+```typescript
+await lair.email.deleteMessage(msg.message_id_url, 'my-agent@agentlair.dev');
+```
+
+### `lair.email.update(messageId, address, options)`
 
 ```typescript
-const msg = await client.readMessage({
-  messageId: inboxMsg.message_id_url, // URL-encoded — safe to use directly
+await lair.email.update(msg.message_id_url, 'my-agent@agentlair.dev', { read: false });
+```
+
+---
+
+## Email Webhooks
+
+Real-time `email.received` events delivered to your URL.
+
+```typescript
+// Register
+const hook = await lair.email.webhooks.create({
   address: 'my-agent@agentlair.dev',
+  url: 'https://myserver.com/webhook',
+  secret: 'my-secret',  // optional — enables X-AgentLair-Signature header
 });
-console.log(msg.body);      // platform-decrypted body
-// For E2E messages: msg.e2e_encrypted, msg.ciphertext, msg.ephemeral_public_key
+
+// List
+const { webhooks } = await lair.email.webhooks.list();
+
+// Delete
+await lair.email.webhooks.delete(hook.id);
 ```
 
 ---
 
 ## Vault
 
-Zero-knowledge secret store. The server stores opaque blobs — it never sees plaintext. Use [`@agentlair/vault-crypto`](https://www.npmjs.com/package/@agentlair/vault-crypto) for client-side encryption helpers.
-
-### `client.vault.put(key, options)`
+Zero-knowledge secret store. Server stores opaque blobs — it never sees plaintext.
+Use [`@agentlair/vault-crypto`](https://www.npmjs.com/package/@agentlair/vault-crypto) for client-side encryption.
 
 ```typescript
-await client.vault.put('openai-key', {
-  ciphertext: encryptedBlob,    // encrypt before storing
-  metadata: { label: 'OpenAI API Key' }, // optional plaintext metadata
-});
+// 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
 ```
 
-### `client.vault.get(key, options?)`
+---
+
+## Stacks
+
+Provision a domain stack (DNS, hosting, email at your own domain).
 
 ```typescript
-const { ciphertext, version, latest_version } = await client.vault.get('openai-key');
-// With @agentlair/vault-crypto:
-const plaintext = await vc.decrypt(ciphertext, 'openai-key');
+// Create
+const stack = await lair.stacks.create({ domain: 'myagent.dev' });
+console.log(stack.nameservers);  // point your domain here
 
-// Specific version:
-const old = await client.vault.get('openai-key', { version: 1 });
+// List
+const { stacks } = await lair.stacks.list();
 ```
 
-### `client.vault.list()`
+---
+
+## Observations
+
+Shared key-value observations for cross-agent coordination.
 
 ```typescript
-const { keys, count, limit } = await client.vault.list();
-// keys: [{ key, version, metadata, created_at, updated_at }]
+// 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();
 ```
 
-### `client.vault.delete(key, options?)`
+---
+
+## Account
 
 ```typescript
-await client.vault.delete('openai-key');           // delete all versions
-await client.vault.delete('openai-key', { version: 2 }); // delete v2 only
+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();
 ```
 
 ---
@@ -168,14 +204,14 @@ await client.vault.delete('openai-key', { version: 2 }); // delete v2 only
 All methods throw `AgentLairError` on non-2xx responses.
 
 ```typescript
-import { AgentLairClient, AgentLairError } from '@agentlair/sdk';
+import { AgentLair, AgentLairError } from '@agentlair/sdk';
 
 try {
-  await client.claimAddress({ address: 'taken@agentlair.dev' });
+  await lair.email.claim('taken@agentlair.dev');
 } catch (e) {
   if (e instanceof AgentLairError) {
-    console.error(e.message);  // human-readable message
-    console.error(e.code);     // machine-readable code (e.g. 'address_taken')
+    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)
   }
 }
@@ -189,26 +225,50 @@ Fully typed — all request/response shapes are exported.
 
 ```typescript
 import type {
+  AgentLairOptions,
   CreateAccountResult,
   InboxMessage,
   FullMessage,
   VaultGetResult,
+  Observation,
+  Stack,
 } from '@agentlair/sdk';
 ```
 
 ---
 
+## Backward Compatibility
+
+`AgentLairClient` (v0.1.x style) is fully retained:
+
+```typescript
+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: 'my-agent@agentlair.dev' });
+await client.sendEmail({ from: '...', to: '...', subject: '...', text: '...' });
+const { messages } = await client.getInbox({ address: 'my-agent@agentlair.dev' });
+
+// 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](https://agentlair.dev/docs/e2e) for the decryption recipe.
+E2E decryption is not included in `@agentlair/sdk` (requires `@noble/curves` for X25519 — breaks zero-dep constraint). See the [E2E encryption guide](https://agentlair.dev/docs/e2e).
 
 ---
 
 ## Related
 
-- [`@agentlair/vault-crypto`](https://www.npmjs.com/package/@agentlair/vault-crypto) — Client-side encryption for the Vault (zero-knowledge AES-256-GCM + HKDF)
+- [`@agentlair/vault-crypto`](https://www.npmjs.com/package/@agentlair/vault-crypto) — Client-side encryption for the Vault
 
 ---