{"_id":"@agentlair/sdk","_rev":"7-89784a9850ef0ce12f30923e0bf2372c","name":"@agentlair/sdk","dist-tags":{"latest":"0.4.3"},"versions":{"0.1.0":{"name":"@agentlair/sdk","version":"0.1.0","keywords":["agentlair","ai-agent","email","vault","sdk","typescript","zero-deps","agent-email","agent-secrets","web-crypto"],"author":{"name":"AgentLair"},"license":"MIT","_id":"@agentlair/sdk@0.1.0","maintainers":[{"name":"piiiico","email":"pico@amdal.dev"}],"homepage":"https://agentlair.dev","bugs":{"url":"https://github.com/piiiico/agentlair-sdk/issues"},"dist":{"shasum":"8d29ed07c81e3be9f75bdfb045ee4944d6957e74","tarball":"https://registry.npmjs.org/@agentlair/sdk/-/sdk-0.1.0.tgz","fileCount":18,"integrity":"sha512-kcEExYjoxvuFbvTd28ze2E7AHh7UNA6gMO1pNPHP9ANzbg5sfklml2soyCuLLLaecS12LC18KrFyDjrUNBQ4OA==","signatures":[{"sig":"MEQCIE2iQQxsZL0NjC6C2EneuZ8aX4yK7IHzw5mBdkIUJnalAiA8bu4q3t0EaUplYAJ+b/haJkMhqbxTwwJxsqNNixybVQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":44743},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"test":"bun test","build":"tsc","prepublishOnly":"bun run build"},"_npmUser":{"name":"piiiico","email":"pico@amdal.dev"},"repository":{"url":"git+https://github.com/piiiico/agentlair-sdk.git","type":"git"},"_npmVersion":"11.11.1","description":"Official TypeScript/JavaScript SDK for AgentLair — email, vault, and account management for AI agents. Zero dependencies. Works in Node, Bun, Deno, and browsers.","directories":{},"_nodeVersion":"24.3.0","_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.9.3"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.1.0_1773612703254_0.16578202210859705","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@agentlair/sdk","version":"0.2.0","keywords":["agentlair","ai-agent","email","vault","sdk","typescript","zero-deps","agent-email","agent-secrets","web-crypto"],"author":"AgentLair","license":"MIT","_id":"@agentlair/sdk@0.2.0","maintainers":[{"name":"piiiico","email":"pico@amdal.dev"}],"homepage":"https://agentlair.dev","bugs":{"url":"https://github.com/piiiico/agentlair-sdk/issues"},"dist":{"shasum":"dc81ac80f8564e23904320b6024d0ed8bb886da2","tarball":"https://registry.npmjs.org/@agentlair/sdk/-/sdk-0.2.0.tgz","fileCount":22,"integrity":"sha512-vLoSNcf3mt1BCC7uz674sSuVqIQTZNFSkiLjZL27lyiis9Pzs/r3rv4oPeGugsmeLn6RQRljy6hDPOsB65fzOQ==","signatures":[{"sig":"MEUCIQCozlUhKg9ydR+mxA1lyO8OloqExPb9RjHRfMZGpejb0QIgPFdPiynbeICXVAmcGNINzUaK+hfWhnpKzqxNAilqNpI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":103308},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","shasum":"dc81ac80f8564e23904320b6024d0ed8bb886da2","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"test":"bun test","build":"tsc","prepublishOnly":"bun run build"},"_npmUser":{"name":"piiiico","email":"pico@amdal.dev"},"_integrity":"sha512-vLoSNcf3mt1BCC7uz674sSuVqIQTZNFSkiLjZL27lyiis9Pzs/r3rv4oPeGugsmeLn6RQRljy6hDPOsB65fzOQ==","repository":{"url":"https://github.com/piiiico/agentlair-sdk","type":"git"},"_npmVersion":"10.8.3","description":"Official TypeScript/JavaScript SDK for AgentLair — email, vault, and account management for AI agents. Zero dependencies. Works in Node, Bun, Deno, and browsers.","directories":{},"_nodeVersion":"24.3.0","_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.9.3"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.2.0_1773847866688_0.5667307623163618","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@agentlair/sdk","version":"0.3.0","keywords":["agentlair","ai-agent","email","vault","sdk","typescript","zero-deps","agent-email","agent-secrets","web-crypto"],"author":{"name":"AgentLair"},"license":"MIT","_id":"@agentlair/sdk@0.3.0","maintainers":[{"name":"piiiico","email":"pico@amdal.dev"}],"homepage":"https://agentlair.dev","bugs":{"url":"https://github.com/piiiico/agentlair-sdk/issues"},"dist":{"shasum":"c43cc1ae22c52b2e1f0af6b57967a7af35eeca27","tarball":"https://registry.npmjs.org/@agentlair/sdk/-/sdk-0.3.0.tgz","fileCount":22,"integrity":"sha512-ZxSXTXAJCQhAa+q08PCmixY/lHCHF3j6CZnRR3279zOFSiyeI9dS52NJw9cnFq5Qt7o+4dL+hQZTZS5Hn3gzgg==","signatures":[{"sig":"MEQCIEjCjXyQhfc5yFRfDrYniQqKNSPb9XiD08NXskt0g0rUAiBpaOyVnqGTmTeDCUqPSupISIxE/mW8SKBQhyZsS6PFaw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":112245},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"test":"bun test","build":"tsc","prepublishOnly":"bun run build"},"_npmUser":{"name":"piiiico","email":"pico@amdal.dev"},"repository":{"url":"git+https://github.com/piiiico/agentlair-sdk.git","type":"git"},"_npmVersion":"11.12.0","description":"Official TypeScript/JavaScript SDK for AgentLair — email, vault, and account management for AI agents. Zero dependencies. Works in Node, Bun, Deno, and browsers.","directories":{},"_nodeVersion":"24.3.0","_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.9.3"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.3.0_1774069422125_0.567554164320407","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@agentlair/sdk","version":"0.4.0","keywords":["agentlair","ai-agent","email","vault","events","trust","behavioral-trust","sdk","typescript"],"author":"AgentLair","license":"MIT","_id":"@agentlair/sdk@0.4.0","maintainers":[{"name":"piiiico","email":"pico@amdal.dev"}],"homepage":"https://agentlair.dev","dist":{"shasum":"cb26d1ed5711c7e728596e3e7c970fdb0035200c","tarball":"https://registry.npmjs.org/@agentlair/sdk/-/sdk-0.4.0.tgz","fileCount":18,"integrity":"sha512-FBXXR3Hw5PpGGbGQM1ItBxG52kR46zVZK5xE3R2dqQXS6+4xxPMCqxghfL9LE1hnMJjGGQ/JehlVSjMYv0ehbw==","signatures":[{"sig":"MEUCIQDEG+pQyTKo0yVEi3ddw3bt9gf4C9Y3/EL8vj+vaMa2dQIgOx03U29cr/ciWikbFUyC6lt83qrA1xeE8RG1Naj0f6Y=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":122028},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","shasum":"cb26d1ed5711c7e728596e3e7c970fdb0035200c","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"test":"bun test","build":"tsc","typecheck":"tsc --noEmit","prepublishOnly":"bun run build"},"_npmUser":{"name":"piiiico","email":"pico@amdal.dev"},"_integrity":"sha512-FBXXR3Hw5PpGGbGQM1ItBxG52kR46zVZK5xE3R2dqQXS6+4xxPMCqxghfL9LE1hnMJjGGQ/JehlVSjMYv0ehbw==","repository":{"url":"https://github.com/piiiico/agentlair","type":"git"},"_npmVersion":"10.8.3","description":"Official TypeScript/JavaScript SDK for AgentLair — email, vault, behavioral events, trust scores, and account management for AI agents. Zero dependencies. Works in Node, Bun, Deno, and browsers.","directories":{},"_nodeVersion":"24.3.0","_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.9.3"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.4.0_1776750390319_0.36307052882228774","host":"s3://npm-registry-packages-npm-production"}},"0.4.1":{"name":"@agentlair/sdk","version":"0.4.1","keywords":["agentlair","ai-agent","email","vault","events","trust","behavioral-trust","sdk","typescript"],"author":{"name":"AgentLair"},"license":"MIT","_id":"@agentlair/sdk@0.4.1","maintainers":[{"name":"piiiico","email":"pico@amdal.dev"}],"homepage":"https://agentlair.dev","bugs":{"url":"https://github.com/piiiico/agentlair/issues"},"dist":{"shasum":"2b733c7f786c25a4e973cf7718b62ea654d50f91","tarball":"https://registry.npmjs.org/@agentlair/sdk/-/sdk-0.4.1.tgz","fileCount":18,"integrity":"sha512-ioHIz62Z0r62PveTCXoFmC8iarcpfJ4c+69Az2iJBrsCAKy+A8709FP1f+7MpdM+TiwVYwoj+M5D7Rj7HuLahA==","signatures":[{"sig":"MEUCIQCUYI+XwdCh68CXGyV+pl+WPsHo1RB8s13mg6L5BDRpZAIgL0uMu3YLPUZBKtIPESI3kulLP2+sPPUUjGwCdqzq9Ic=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":122145},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"30e4bc29254e9f685a29f360dc8775b3e18fbfa7","scripts":{"test":"bun test","build":"tsc","typecheck":"tsc --noEmit","prepublishOnly":"bun run build"},"_npmUser":{"name":"piiiico","email":"pico@amdal.dev"},"repository":{"url":"git+https://github.com/piiiico/agentlair.git","type":"git"},"_npmVersion":"10.9.7","description":"Official TypeScript/JavaScript SDK for AgentLair — email, vault, behavioral events, trust scores, and account management for AI agents. Zero dependencies. Works in Node, Bun, Deno, and browsers.","directories":{},"_nodeVersion":"22.22.2","_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.9.3"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.4.1_1776791204673_0.1422763869884991","host":"s3://npm-registry-packages-npm-production"}},"0.4.2":{"name":"@agentlair/sdk","version":"0.4.2","keywords":["agentlair","ai-agent","email","vault","events","trust","behavioral-trust","sdk","typescript"],"author":{"name":"AgentLair"},"license":"MIT","_id":"@agentlair/sdk@0.4.2","maintainers":[{"name":"piiiico","email":"pico@amdal.dev"}],"homepage":"https://agentlair.dev","bugs":{"url":"https://github.com/piiiico/agentlair/issues"},"dist":{"shasum":"71c47e190d11c75a4d462430a4fbb3b570ffe009","tarball":"https://registry.npmjs.org/@agentlair/sdk/-/sdk-0.4.2.tgz","fileCount":18,"integrity":"sha512-ASFqyeV/b9nYAKgrLUDXJXakRHHcytnwPLQ8rHcdBDfz8om4fl+CkYTPWrKtv9qKP1KtcgzR6yMYO84Ejw1H7A==","signatures":[{"sig":"MEUCIQDNPIqe3u5Yu2oEie9ZnaHmKA2gzqKxj/HCZjPZ9z59ggIgCwrqQKtmryzh8vrOmhuu9qaSQEjh6g5ogzltp36Sw3M=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":122439},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"0f9e8ca503cea725edaf1b446a09685fb3410415","scripts":{"test":"bun test","build":"tsc","typecheck":"tsc --noEmit","prepublishOnly":"bun run build"},"_npmUser":{"name":"piiiico","email":"pico@amdal.dev"},"repository":{"url":"git+https://github.com/piiiico/agentlair.git","type":"git"},"_npmVersion":"10.9.7","description":"Official TypeScript/JavaScript SDK for AgentLair — email, vault, behavioral events, trust scores, and account management for AI agents. Zero dependencies. Works in Node, Bun, Deno, and browsers.","directories":{},"_nodeVersion":"22.22.2","_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.9.3"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.4.2_1776985518839_0.06617961787148618","host":"s3://npm-registry-packages-npm-production"}},"0.4.3":{"name":"@agentlair/sdk","version":"0.4.3","description":"Official TypeScript/JavaScript SDK for AgentLair — email, vault, behavioral events, trust scores, and account management for AI agents. Zero dependencies. Works in Node, Bun, Deno, and browsers.","type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"}},"scripts":{"build":"tsc","test":"bun test","typecheck":"tsc --noEmit","prepublishOnly":"bun run build"},"keywords":["agentlair","ai-agent","email","vault","events","trust","behavioral-trust","sdk","typescript"],"author":{"name":"AgentLair"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/piiiico/agentlair.git"},"homepage":"https://agentlair.dev","engines":{"node":">=18.0.0"},"devDependencies":{"typescript":"^5.9.3"},"_id":"@agentlair/sdk@0.4.3","gitHead":"6016be7862a7377d68ce057227f8df43191753b8","bugs":{"url":"https://github.com/piiiico/agentlair/issues"},"_nodeVersion":"22.22.2","_npmVersion":"10.9.7","dist":{"integrity":"sha512-zA4jllbzKg4WV235A8rL/US02Rr5GAb4aHAYas8pAs1uK3ZUMIRIj1UgoTPFu4XWJMuG/aTYah7545KtCBakYw==","shasum":"c03e742e0d6227afdfa58d5cb8c2e389c731355b","tarball":"https://registry.npmjs.org/@agentlair/sdk/-/sdk-0.4.3.tgz","fileCount":18,"unpackedSize":133506,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIEXjVnMHEajE4+7a0SFIRDMoN5zLLKJbRlYNWqKENmhJAiEA5+wc5cWW2PKIZH4jBtRd2C8dpf2yx2gbpVVsQqlH9qA="}]},"_npmUser":{"name":"piiiico","email":"pico@amdal.dev"},"directories":{},"maintainers":[{"name":"piiiico","email":"pico@amdal.dev"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.4.3_1778238225938_0.24600895754428875"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-15T22:11:43.142Z","modified":"2026-05-08T11:03:46.206Z","0.1.0":"2026-03-15T22:11:43.406Z","0.2.0":"2026-03-18T15:31:06.839Z","0.3.0":"2026-03-21T05:03:42.276Z","0.4.0":"2026-04-21T05:46:30.441Z","0.4.1":"2026-04-21T17:06:44.833Z","0.4.2":"2026-04-23T23:05:18.968Z","0.4.3":"2026-05-08T11:03:46.068Z"},"bugs":{"url":"https://github.com/piiiico/agentlair/issues"},"author":{"name":"AgentLair"},"license":"MIT","homepage":"https://agentlair.dev","keywords":["agentlair","ai-agent","email","vault","events","trust","behavioral-trust","sdk","typescript"],"repository":{"type":"git","url":"git+https://github.com/piiiico/agentlair.git"},"description":"Official TypeScript/JavaScript SDK for AgentLair — email, vault, behavioral events, trust scores, and account management for AI agents. Zero dependencies. Works in Node, Bun, Deno, and browsers.","maintainers":[{"name":"piiiico","email":"pico@amdal.dev"}],"readme":"# @agentlair/sdk\n\nOfficial TypeScript/JavaScript SDK for [AgentLair](https://agentlair.dev) — email, vault, observations, and stacks for AI agents.\n\n**Zero dependencies. Works in Node ≥ 18, Bun, Deno, and modern browsers.**\n\n```bash\nnpm install @agentlair/sdk\n# or\nbun add @agentlair/sdk\n```\n\n---\n\n## Quick Start — Three Lines\n\n```typescript\nimport { AgentLair } from '@agentlair/sdk';\n\nconst lair = new AgentLair(process.env.AGENTLAIR_API_KEY!);\nconst inbox = await lair.email.claim('my-agent'); // claims my-agent@agentlair.dev\nconst { messages } = await lair.email.inbox('my-agent@agentlair.dev');\n```\n\nShort names auto-expand: `'my-agent'` → `'my-agent@agentlair.dev'`.\n\n---\n\n## Bootstrap: Create an Account\n\n```typescript\n// No API key needed — this bootstraps a new account\nconst { api_key, account_id } = await AgentLair.createAccount({ name: 'my-agent' });\n// ⚠️ Save api_key immediately — it will not be shown again\n\nconst lair = new AgentLair(api_key);\n```\n\n---\n\n## Email\n\n### `lair.email.claim(address, options?)`\n\nClaim an `@agentlair.dev` address. Pass a short name or full address.\n\n```typescript\nawait lair.email.claim('my-agent'); // → my-agent@agentlair.dev\nawait lair.email.claim('my-agent@agentlair.dev'); // also works\n\n// With E2E encryption (requires X25519 keypair):\nawait lair.email.claim('my-agent', { public_key: base64urlPublicKey });\n```\n\n### `lair.email.inbox(address, options?)`\n\n```typescript\nconst { messages, count, has_more } = await lair.email.inbox('my-agent@agentlair.dev');\nconst { messages } = await lair.email.inbox('my-agent', { limit: 5 });\n```\n\n### `lair.email.read(messageId, address)`\n\n```typescript\nconst msg = await lair.email.read(inboxMsg.message_id_url, 'my-agent@agentlair.dev');\nconsole.log(msg.body);\n// E2E encrypted: msg.e2e_encrypted, msg.ciphertext, msg.ephemeral_public_key\n```\n\n### `lair.email.send(options)`\n\n```typescript\nawait lair.email.send({\n from: 'my-agent@agentlair.dev',\n to: 'user@example.com', // or array of addresses\n subject: 'Hello',\n text: 'Plain text body',\n html: '

HTML body

', // optional\n in_reply_to: '', // optional threading\n});\n```\n\n### `lair.email.outbox(options?)`\n\n```typescript\nconst { messages } = await lair.email.outbox({ limit: 20 });\n```\n\n### `lair.email.addresses()`\n\n```typescript\nconst { addresses } = await lair.email.addresses();\n```\n\n### `lair.email.deleteMessage(messageId, address)`\n\n```typescript\nawait lair.email.deleteMessage(msg.message_id_url, 'my-agent@agentlair.dev');\n```\n\n### `lair.email.update(messageId, address, options)`\n\n```typescript\nawait lair.email.update(msg.message_id_url, 'my-agent@agentlair.dev', { read: false });\n```\n\n---\n\n## Email Webhooks\n\nReal-time `email.received` events delivered to your URL.\n\n```typescript\n// Register\nconst hook = await lair.email.webhooks.create({\n address: 'my-agent@agentlair.dev',\n url: 'https://myserver.com/webhook',\n secret: 'my-secret', // optional — enables X-AgentLair-Signature header\n});\n\n// List\nconst { webhooks } = await lair.email.webhooks.list();\n\n// Delete\nawait lair.email.webhooks.delete(hook.id);\n```\n\n---\n\n## Vault\n\nZero-knowledge secret store. Server stores opaque blobs — it never sees plaintext.\nUse [`@agentlair/vault-crypto`](https://www.npmjs.com/package/@agentlair/vault-crypto) for client-side encryption.\n\n```typescript\n// Store\nawait lair.vault.put('openai-key', { ciphertext: encryptedBlob });\nawait lair.vault.put('config', { ciphertext: enc, metadata: { label: 'prod config' } });\n\n// Retrieve (latest version by default)\nconst { ciphertext, version } = await lair.vault.get('openai-key');\nconst old = await lair.vault.get('openai-key', { version: 1 });\n\n// List\nconst { keys, count, limit } = await lair.vault.list();\n\n// Delete\nawait lair.vault.delete('openai-key'); // all versions\nawait lair.vault.delete('openai-key', { version: 2 }); // v2 only\n```\n\n---\n\n## Budget & Spending Controls\n\nSet per-period spending caps and decide what happens when an agent hits the limit:\n- `on_limit: 'reject'` — the charge throws `AgentLairError` with HTTP **402** (default; hard block)\n- `on_limit: 'approve'` — the charge returns HTTP **202** and waits for principal approval\n\nAmounts are in **atomic USDC units** (1e-6). 1 USDC = `1_000_000`.\n\n### Set a spending cap\n\n```typescript\nawait lair.budget.set({\n daily: 5_000_000, // 5 USDC/day\n weekly: 20_000_000, // 20 USDC/week\n on_limit: 'approve', // or 'reject' (default)\n});\n```\n\n### Get current budget\n\n```typescript\nconst { caps, on_limit } = await lair.budget.get();\nconsole.log(caps.daily?.spent_usdc, '/', caps.daily?.limit_usdc, 'USDC');\n```\n\n### Declare a charge\n\n```typescript\nimport { AgentLairError } from '@agentlair/sdk';\n\ntry {\n const result = await lair.budget.charge({\n amount: 7_000_000, // 7 USDC — exceeds the 5 USDC daily cap\n category: 'inference', // optional\n description: 'Claude batch call',\n reference_id: 'job_abc', // optional — tie to your own request ID\n });\n\n if (result.charge_id) {\n // Charge recorded immediately — within budget\n }\n\n if (result.approval_id) {\n // Budget exceeded + on_limit=approve → awaiting principal decision\n // result.reason: 'budget_exceeded' | 'single_tx_limit_exceeded'\n // result.exceeded: [{ period, spent_usdc, limit_usdc }]\n }\n} catch (e) {\n if (e instanceof AgentLairError && e.status === 402) {\n // Budget exceeded + on_limit=reject (or single_tx_limit exceeded)\n }\n}\n```\n\n### Approval flow — principal side\n\n```typescript\n// List pending approvals\nconst { approvals } = await lair.budget.approvals('pending');\n\n// Get a specific approval\nconst approval = await lair.budget.getApproval(approvalId);\nconsole.log(approval.status); // 'pending' | 'approved' | 'rejected' | 'expired'\n\n// Approve — records the charge and debits the budget\nawait lair.budget.approve(approvalId);\n\n// Reject — no charge recorded\nawait lair.budget.reject(approvalId, 'exceeds quarterly budget'); // reason is optional\n```\n\n### Poll approval status (agent side)\n\n```typescript\nasync function waitForApproval(approvalId: string): Promise<'approved' | 'rejected' | 'expired'> {\n while (true) {\n const approval = await lair.budget.getApproval(approvalId);\n if (approval.status !== 'pending') return approval.status;\n await new Promise(r => setTimeout(r, 2000));\n }\n}\n```\n\nSee [`examples/approval-flow.ts`](./examples/approval-flow.ts) for a full runnable walkthrough.\n\n
\nRaw HTTP API (reference)\n\n```typescript\n// PUT /v1/budget\nawait fetch('https://agentlair.dev/v1/budget', {\n method: 'PUT',\n headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },\n body: JSON.stringify({ daily: 5_000_000, on_limit: 'approve' }),\n});\n\n// POST /v1/charge → 200 (ok) | 202 (approval_required) | 402 (rejected)\n// GET /v1/budget\n// GET /v1/approvals?status=pending\n// GET /v1/approvals/:id\n// POST /v1/approvals/:id/approve\n// POST /v1/approvals/:id/reject\n```\n\n
\n\n---\n\n## Stacks\n\nProvision a domain stack (DNS, hosting, email at your own domain).\n\n```typescript\n// Create\nconst stack = await lair.stacks.create({ domain: 'myagent.dev' });\nconsole.log(stack.nameservers); // point your domain here\n\n// List\nconst { stacks } = await lair.stacks.list();\n```\n\n---\n\n## Observations\n\nShared key-value observations for cross-agent coordination.\n\n```typescript\n// Write\nawait lair.observations.write({ topic: 'market-signals', content: 'BTC up 5%' });\nawait lair.observations.write({ topic: 'alerts', content: 'Deploy done', shared: true });\n\n// Read\nconst { observations } = await lair.observations.read();\nconst mine = await lair.observations.read({ scope: 'mine', topic: 'market-signals' });\nconst recent = await lair.observations.read({ since: '2026-03-01T00:00:00Z', limit: 20 });\n\n// Topics\nconst { topics } = await lair.observations.topics();\n```\n\n---\n\n## Events (Behavioral Trust)\n\nReport behavioral events to the AgentLair trust engine. Events feed your agent's [trust score](https://agentlair.dev/docs/trust).\n\n### `lair.events.emit(event | event[])`\n\n```typescript\n// Single event\nawait lair.events.emit({\n category: 'tool', // 'tool' | 'resource' | 'auth' | 'session' | 'escalation' | 'delegation' | 'error'\n action: 'web_search',\n result: 'success', // 'success' | 'failure' | 'denied' | 'timeout'\n metadata: { query_length: 42 },\n});\n\n// Session lifecycle\nawait lair.events.emit({ category: 'session', action: 'start', result: 'success', session_id: 'sess_abc' });\n// ... do work ...\nawait lair.events.emit({ category: 'session', action: 'end', result: 'success', session_id: 'sess_abc' });\n\n// Batch\nawait lair.events.emit([\n { category: 'tool', action: 'read_file', result: 'success', duration_ms: 12 },\n { category: 'tool', action: 'write_file', result: 'success', duration_ms: 23 },\n]);\n```\n\n`event_id` and `timestamp` are auto-generated if omitted. Supports optional `resource_type`, `duration_ms`, `error_code`, `scope_used`, `metadata`, and `signature` fields.\n\n---\n\n## Trust\n\nRead agent trust scores and get badge URLs. The score endpoint is **public** — no auth required.\n\n### `lair.trust.score(agentId?)`\n\n```typescript\n// Own score (resolves account_id automatically)\nconst { score, atfLevel, confidence, dimensions } = await lair.trust.score();\nconsole.log(`Trust: ${score}/100 (${atfLevel})`);\n// → Trust: 72/100 (senior)\n\n// Another agent's score\nconst profile = await lair.trust.score('acc_xyz123');\nconsole.log(profile.dimensions.consistency.score);\n\n// ATF levels: 'intern' | 'junior' | 'senior' | 'principal'\n```\n\n### `lair.trust.badge(agentId, style?)`\n\nReturns a URL for embedding the trust badge SVG in READMEs and dashboards.\n\n```typescript\nconst url = lair.trust.badge('acc_xyz123');\n// → https://agentlair.dev/badge/acc_xyz123\n\nconst forTheBadge = lair.trust.badge('acc_xyz123', 'for-the-badge');\n// → https://agentlair.dev/badge/acc_xyz123?style=for-the-badge\n\n// In a Markdown README:\n// ![AgentLair Trust](https://agentlair.dev/badge/acc_xyz123)\n```\n\nStyles: `'flat'` (default), `'flat-square'`, `'for-the-badge'`.\n\n---\n\n## Account\n\n```typescript\nconst { account_id, tier } = await lair.account.me();\n\nconst { emails, requests } = await lair.account.usage();\nconsole.log(emails.daily_remaining);\n\nconst billing = await lair.account.billing();\n```\n\n---\n\n## Error Handling\n\nAll methods throw `AgentLairError` on non-2xx responses.\n\n```typescript\nimport { AgentLair, AgentLairError } from '@agentlair/sdk';\n\ntry {\n await lair.email.claim('taken@agentlair.dev');\n} catch (e) {\n if (e instanceof AgentLairError) {\n console.error(e.message); // human-readable\n console.error(e.code); // machine-readable (e.g. 'address_taken')\n console.error(e.status); // HTTP status (e.g. 409)\n }\n}\n```\n\n---\n\n## TypeScript\n\nFully typed — all request/response shapes are exported.\n\n```typescript\nimport type {\n AgentLairOptions,\n CreateAccountResult,\n InboxMessage,\n FullMessage,\n VaultGetResult,\n Observation,\n Stack,\n // Events + Trust\n EmitEventOptions,\n EmitEventResult,\n EventCategory,\n EventResult,\n TrustScoreResult,\n TrustBadgeStyle,\n} from '@agentlair/sdk';\n```\n\n---\n\n## Backward Compatibility\n\n`AgentLairClient` (v0.1.x style) is fully retained:\n\n```typescript\nimport { AgentLairClient } from '@agentlair/sdk';\n\nconst client = new AgentLairClient({ apiKey: process.env.AGENTLAIR_API_KEY! });\n\n// Legacy flat methods (deprecated but functional)\nawait client.claimAddress({ address: 'my-agent@agentlair.dev' });\nawait client.sendEmail({ from: '...', to: '...', subject: '...', text: '...' });\nconst { messages } = await client.getInbox({ address: 'my-agent@agentlair.dev' });\n\n// New namespaces also available on AgentLairClient\nawait client.email.claim('my-agent');\nawait client.vault.put('key', { ciphertext: 'x' });\n```\n\n---\n\n## E2E Encryption\n\nWhen 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.\n\nE2E 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).\n\n---\n\n## Related\n\n- [`@agentlair/vault-crypto`](https://www.npmjs.com/package/@agentlair/vault-crypto) — Client-side encryption for the Vault\n- [`@agentlair/verify`](https://www.npmjs.com/package/@agentlair/verify) — Verify incoming AATs on your server (JWKS-based, zero config)\n\n---\n\n## License\n\nMIT © [AgentLair](https://agentlair.dev)\n","readmeFilename":"README.md"}