@agentlair/sdk 0.1.0 → 0.2.0

package/dist/client.js

@@ -1,156 +1,432 @@
 /**
- * @agentlair/sdk — AgentLairClient
+ * @agentlair/sdk — AgentLair + AgentLairClient
  *
- * Official TypeScript/JavaScript SDK for AgentLair.
- * Zero dependencies. Works in Node ≥ 18, Bun, Deno, and modern browsers.
+ * `AgentLair` is the primary class. Accepts an API key string directly.
+ * `AgentLairClient` is the legacy class (accepts options object) — still fully supported.
  *
- * @example
+ * @example Three-line onboarding
+ * const lair = new AgentLair(process.env.AGENTLAIR_API_KEY!);
+ * const inbox = await lair.email.claim('my-agent');  // auto-expands to my-agent@agentlair.dev
+ * const { messages } = await lair.email.inbox('my-agent@agentlair.dev');
+ *
+ * @example Full flow
  * // Create a new account (no API key needed)
- * const { api_key, account_id } = await AgentLairClient.createAccount({ name: 'my-agent' });
+ * const { api_key } = await AgentLair.createAccount({ name: 'my-agent' });
+ *
+ * const lair = new AgentLair(api_key);
+ * await lair.email.claim('my-agent');
+ * await lair.email.send({ from: 'my-agent@agentlair.dev', to: 'user@example.com', subject: 'Hello', text: 'Hi!' });
+ * const { messages } = await lair.email.inbox('my-agent@agentlair.dev');
  *
- * @example
- * // Use an existing key
- * const client = new AgentLairClient({ apiKey: process.env.AGENTLAIR_API_KEY! });
- * await client.claimAddress({ address: 'my-agent@agentlair.dev' });
- * await client.sendEmail({ from: 'my-agent@agentlair.dev', to: 'user@example.com', subject: 'Hello', text: 'Hi!' });
- * const inbox = await client.getInbox({ address: 'my-agent@agentlair.dev' });
+ * // Vault: store secrets (zero-knowledge — use @agentlair/vault-crypto to encrypt first)
+ * await lair.vault.put('openai-key', { ciphertext: encryptedBlob });
+ * const { ciphertext } = await lair.vault.get('openai-key');
  */
 import { AgentLairError } from './errors.js';
 const DEFAULT_BASE_URL = 'https://agentlair.dev';
-// ─── VaultNamespace ───────────────────────────────────────────────────────────
+// ─── Helpers ──────────────────────────────────────────────────────────────────
 /**
- * vault.put / vault.get / vault.list / vault.delete
- *
- * The AgentLair Vault is a zero-knowledge secret store.
- * The server stores opaque encrypted blobs — plaintext never leaves your client.
- * Use @agentlair/vault-crypto for client-side encryption helpers.
+ * Expand a short name like "my-agent" to "my-agent@agentlair.dev".
+ * If the address already contains "@", returns it as-is.
  */
-class VaultNamespace {
-    _request;
-    constructor(_request) {
-        this._request = _request;
+function expandAddress(address) {
+    return address.includes('@') ? address : `${address}@agentlair.dev`;
+}
+// ─── Internal request helper (shared by both classes) ─────────────────────────
+async function makeRequest(baseUrl, apiKey, method, path, opts = {}) {
+    const url = new URL(baseUrl + path);
+    if (opts.query) {
+        for (const [k, v] of Object.entries(opts.query)) {
+            url.searchParams.set(k, v);
+        }
+    }
+    const headers = {
+        'Content-Type': 'application/json',
+    };
+    if (opts.auth !== null) {
+        headers['Authorization'] = `Bearer ${opts.auth ?? apiKey}`;
+    }
+    const response = await fetch(url.toString(), {
+        method,
+        headers,
+        body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+    });
+    let data;
+    const contentType = response.headers.get('content-type') ?? '';
+    if (contentType.includes('application/json')) {
+        data = await response.json();
+    }
+    else {
+        data = await response.text();
+    }
+    if (!response.ok) {
+        const body = data;
+        throw new AgentLairError(body?.message ?? `HTTP ${response.status}`, response.status, body?.error ?? 'error');
+    }
+    return data;
+}
+// ─── WebhooksNamespace ────────────────────────────────────────────────────────
+class WebhooksNamespace {
+    _req;
+    constructor(_req) {
+        this._req = _req;
     }
     /**
-     * Store an encrypted blob in the Vault.
+     * Register a webhook URL to receive real-time `email.received` events.
      *
-     * Each PUT creates a new version (append-only, versioned).
-     * Free tier: up to 50 keys, 3 versions each.
+     * @example
+     * const hook = await lair.email.webhooks.create({
+     *   address: 'my-agent@agentlair.dev',
+     *   url: 'https://myserver.com/webhook',
+     *   secret: 'my-secret',
+     * });
+     */
+    async create(options) {
+        return this._req('POST', '/v1/email/webhooks', {
+            body: { ...options, address: expandAddress(options.address) },
+        });
+    }
+    /**
+     * List registered webhooks, optionally filtered by address.
      *
      * @example
-     * // With @agentlair/vault-crypto:
-     * const vc = VaultCrypto.fromSeed(seed);
-     * const ciphertext = await vc.encrypt('sk-openai-...', 'openai-key');
-     * await client.vault.put('openai-key', { ciphertext });
+     * const { webhooks } = await lair.email.webhooks.list();
      */
-    async put(key, options) {
-        return this._request('PUT', `/v1/vault/${encodeURIComponent(key)}`, {
-            body: options,
+    async list(options = {}) {
+        const query = {};
+        if (options.address)
+            query.address = expandAddress(options.address);
+        return this._req('GET', '/v1/email/webhooks', { query });
+    }
+    /**
+     * Delete a webhook by ID.
+     *
+     * @example
+     * await lair.email.webhooks.delete('wh_abc123');
+     */
+    async delete(id) {
+        return this._req('DELETE', `/v1/email/webhooks/${encodeURIComponent(id)}`);
+    }
+}
+// ─── EmailNamespace ───────────────────────────────────────────────────────────
+class EmailNamespace {
+    _req;
+    /** Webhook management: webhooks.create / webhooks.list / webhooks.delete */
+    webhooks;
+    constructor(_req) {
+        this._req = _req;
+        this.webhooks = new WebhooksNamespace(_req);
+    }
+    /**
+     * Claim an @agentlair.dev email address.
+     *
+     * Pass a short name (e.g. `"my-agent"`) and it auto-expands to `my-agent@agentlair.dev`.
+     *
+     * @example
+     * await lair.email.claim('my-agent');                    // → my-agent@agentlair.dev
+     * await lair.email.claim('my-agent@agentlair.dev');      // also works
+     */
+    async claim(address, options = {}) {
+        return this._req('POST', '/v1/email/claim', {
+            body: { ...options, address: expandAddress(address) },
         });
     }
     /**
-     * Retrieve an encrypted blob from the Vault.
+     * List all @agentlair.dev addresses claimed by this account.
+     *
+     * @example
+     * const { addresses } = await lair.email.addresses();
+     */
+    async addresses() {
+        return this._req('GET', '/v1/email/addresses');
+    }
+    /**
+     * Get inbox messages (previews — no full body).
+     * Use `read()` for the full body of a specific message.
      *
-     * Returns the latest version by default. Pass `version` for a specific one.
+     * @example
+     * const { messages } = await lair.email.inbox('my-agent@agentlair.dev');
+     * const { messages } = await lair.email.inbox('my-agent', { limit: 5 });
+     */
+    async inbox(address, options = {}) {
+        const query = { address: expandAddress(address) };
+        if (options.limit !== undefined)
+            query.limit = String(options.limit);
+        return this._req('GET', '/v1/email/inbox', { query });
+    }
+    /**
+     * Read the full body of a message. Marks as read.
+     *
+     * @example
+     * const msg = await lair.email.read(inboxMsg.message_id_url, 'my-agent@agentlair.dev');
+     * console.log(msg.body);
+     */
+    async read(messageId, address) {
+        return this._req('GET', `/v1/email/messages/${messageId}`, { query: { address: expandAddress(address) } });
+    }
+    /**
+     * Delete a message.
      *
      * @example
-     * const { ciphertext } = await client.vault.get('openai-key');
-     * // With @agentlair/vault-crypto:
-     * const plaintext = await vc.decrypt(ciphertext, 'openai-key');
+     * await lair.email.deleteMessage(inboxMsg.message_id_url, 'my-agent@agentlair.dev');
+     */
+    async deleteMessage(messageId, address) {
+        return this._req('DELETE', `/v1/email/messages/${messageId}`, { query: { address: expandAddress(address) } });
+    }
+    /**
+     * Update message properties (mark read/unread).
+     *
+     * @example
+     * await lair.email.update(msg.message_id_url, 'my-agent@agentlair.dev', { read: false });
+     */
+    async update(messageId, address, options) {
+        return this._req('PATCH', `/v1/email/messages/${messageId}`, { query: { address: expandAddress(address) }, body: options });
+    }
+    /**
+     * Send an email from an address you own.
+     *
+     * @example
+     * await lair.email.send({
+     *   from: 'my-agent@agentlair.dev',
+     *   to: 'user@example.com',
+     *   subject: 'Hello',
+     *   text: 'Hi from an AI agent!',
+     * });
+     */
+    async send(options) {
+        return this._req('POST', '/v1/email/send', { body: options });
+    }
+    /**
+     * List sent messages (outbox).
+     *
+     * @example
+     * const { messages } = await lair.email.outbox({ limit: 5 });
+     */
+    async outbox(options = {}) {
+        const query = {};
+        if (options.limit !== undefined)
+            query.limit = String(options.limit);
+        return this._req('GET', '/v1/email/outbox', { query });
+    }
+}
+// ─── VaultNamespace ───────────────────────────────────────────────────────────
+/**
+ * Zero-knowledge secret store.
+ * Server stores opaque encrypted blobs — plaintext never leaves your client.
+ * Use @agentlair/vault-crypto for client-side encryption.
+ */
+class VaultNamespace {
+    _req;
+    constructor(_req) {
+        this._req = _req;
+    }
+    /**
+     * Store an encrypted blob (versioned, append-only).
+     *
+     * @example
+     * await lair.vault.put('openai-key', { ciphertext: encryptedBlob });
+     */
+    async put(key, options) {
+        return this._req('PUT', `/v1/vault/${encodeURIComponent(key)}`, { body: options });
+    }
+    /**
+     * Retrieve an encrypted blob. Returns latest version by default.
+     *
+     * @example
+     * const { ciphertext } = await lair.vault.get('openai-key');
+     * const old = await lair.vault.get('openai-key', { version: 1 });
      */
     async get(key, options = {}) {
         const query = {};
         if (options.version !== undefined)
             query.version = String(options.version);
-        return this._request('GET', `/v1/vault/${encodeURIComponent(key)}`, { query });
+        return this._req('GET', `/v1/vault/${encodeURIComponent(key)}`, { query });
     }
     /**
-     * List all Vault keys for this account (metadata only — no ciphertext).
+     * List all Vault keys (metadata only).
      *
      * @example
-     * const { keys, count, limit } = await client.vault.list();
+     * const { keys, count, limit } = await lair.vault.list();
      */
     async list() {
-        return this._request('GET', '/v1/vault/');
+        return this._req('GET', '/v1/vault/');
     }
     /**
-     * Delete a Vault key (all versions) or a specific version.
-     *
-     * Pass `version` to delete only that version. Omit to delete all versions.
+     * Delete a key (all versions) or a specific version.
      *
      * @example
-     * await client.vault.delete('openai-key');           // delete all versions
-     * await client.vault.delete('openai-key', { version: 2 }); // delete v2 only
+     * await lair.vault.delete('openai-key');
+     * await lair.vault.delete('openai-key', { version: 2 });
      */
     async delete(key, options = {}) {
         const query = {};
         if (options.version !== undefined)
             query.version = String(options.version);
-        return this._request('DELETE', `/v1/vault/${encodeURIComponent(key)}`, {
-            query,
-        });
+        return this._req('DELETE', `/v1/vault/${encodeURIComponent(key)}`, { query });
     }
 }
-// ─── AgentLairClient ──────────────────────────────────────────────────────────
-export class AgentLairClient {
+// ─── StacksNamespace ──────────────────────────────────────────────────────────
+class StacksNamespace {
+    _req;
+    constructor(_req) {
+        this._req = _req;
+    }
+    /**
+     * Create a domain stack. Points nameservers to AgentLair DNS.
+     * Beta: DNS provisioning is stubbed. Full CF DNS integration coming Q2 2026.
+     *
+     * @example
+     * const stack = await lair.stacks.create({ domain: 'myagent.dev' });
+     */
+    async create(options) {
+        return this._req('POST', '/v1/stack', { body: options });
+    }
+    /**
+     * List all domain stacks for this account.
+     *
+     * @example
+     * const { stacks } = await lair.stacks.list();
+     */
+    async list() {
+        return this._req('GET', '/v1/stack');
+    }
+}
+// ─── ObservationsNamespace ────────────────────────────────────────────────────
+class ObservationsNamespace {
+    _req;
+    constructor(_req) {
+        this._req = _req;
+    }
+    /**
+     * Write a structured observation. Account-scoped by default.
+     * Set `shared: true` to make visible to all authenticated agents.
+     *
+     * @example
+     * await lair.observations.write({ topic: 'market-signals', content: 'BTC up 5%' });
+     */
+    async write(options) {
+        return this._req('POST', '/v1/observations', { body: options });
+    }
+    /**
+     * Read observations. Returns own + shared by default.
+     *
+     * @example
+     * const { observations } = await lair.observations.read({ topic: 'market-signals' });
+     * const shared = await lair.observations.read({ scope: 'shared' });
+     */
+    async read(options = {}) {
+        const query = {};
+        if (options.topic)
+            query.topic = options.topic;
+        if (options.agent_id)
+            query.agent_id = options.agent_id;
+        if (options.since)
+            query.since = options.since;
+        if (options.scope)
+            query.scope = options.scope;
+        if (options.limit !== undefined)
+            query.limit = String(options.limit);
+        return this._req('GET', '/v1/observations', { query });
+    }
+    /**
+     * List distinct topics with observation count.
+     *
+     * @example
+     * const { topics } = await lair.observations.topics();
+     */
+    async topics() {
+        return this._req('GET', '/v1/observations/topics');
+    }
+}
+// ─── AccountNamespace ─────────────────────────────────────────────────────────
+class AccountNamespace {
+    _req;
+    constructor(_req) {
+        this._req = _req;
+    }
+    /**
+     * Get the current account profile.
+     *
+     * @example
+     * const { account_id, tier } = await lair.account.me();
+     */
+    async me() {
+        return this._req('GET', '/v1/account/me');
+    }
+    /**
+     * Get current usage statistics.
+     *
+     * @example
+     * const { emails } = await lair.account.usage();
+     * console.log(emails.daily_remaining);
+     */
+    async usage() {
+        return this._req('GET', '/v1/usage');
+    }
+    /**
+     * Get billing information.
+     *
+     * @example
+     * const billing = await lair.account.billing();
+     */
+    async billing() {
+        return this._req('GET', '/v1/billing');
+    }
+}
+// ─── AgentLair (primary class) ────────────────────────────────────────────────
+/**
+ * AgentLair — primary SDK class.
+ *
+ * Accepts an API key string directly (or an options object for advanced config).
+ *
+ * @example Three-line onboarding
+ * const lair = new AgentLair(process.env.AGENTLAIR_API_KEY!);
+ * const inbox = await lair.email.claim('my-agent');
+ * const { messages } = await lair.email.inbox('my-agent@agentlair.dev');
+ */
+export class AgentLair {
     _apiKey;
     _baseUrl;
+    /** Email: claim / inbox / send / read / deleteMessage / update / outbox / addresses / webhooks */
+    email;
+    /** Vault: put / get / list / delete */
+    vault;
+    /** Stacks: create / list */
+    stacks;
+    /** Observations: write / read / topics */
+    observations;
+    /** Account: me / usage / billing */
+    account;
     /**
-     * Namespaced Vault operations: vault.put / vault.get / vault.list / vault.delete
+     * @param apiKeyOrOptions API key string (e.g. "al_live_...") or options object
      */
-    vault;
-    constructor(options) {
-        this._apiKey = options.apiKey;
-        this._baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, '');
-        this.vault = new VaultNamespace(this._request.bind(this));
-    }
-    // ─── Internal request helper ─────────────────────────────────────────────
-    async _request(method, path, opts = {}) {
-        const url = new URL(this._baseUrl + path);
-        if (opts.query) {
-            for (const [k, v] of Object.entries(opts.query)) {
-                url.searchParams.set(k, v);
-            }
-        }
-        const headers = {
-            'Content-Type': 'application/json',
-        };
-        // auth defaults to Bearer <apiKey>; pass null to skip auth
-        if (opts.auth !== null) {
-            headers['Authorization'] = `Bearer ${opts.auth ?? this._apiKey}`;
-        }
-        const response = await fetch(url.toString(), {
-            method,
-            headers,
-            body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
-        });
-        let data;
-        const contentType = response.headers.get('content-type') ?? '';
-        if (contentType.includes('application/json')) {
-            data = await response.json();
+    constructor(apiKeyOrOptions) {
+        if (typeof apiKeyOrOptions === 'string') {
+            this._apiKey = apiKeyOrOptions;
+            this._baseUrl = DEFAULT_BASE_URL;
         }
         else {
-            data = await response.text();
-        }
-        if (!response.ok) {
-            const body = data;
-            throw new AgentLairError(body?.message ?? `HTTP ${response.status}`, response.status, body?.error ?? 'error');
+            this._apiKey = apiKeyOrOptions.apiKey;
+            this._baseUrl = (apiKeyOrOptions.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, '');
         }
-        return data;
+        const req = this._request.bind(this);
+        this.email = new EmailNamespace(req);
+        this.vault = new VaultNamespace(req);
+        this.stacks = new StacksNamespace(req);
+        this.observations = new ObservationsNamespace(req);
+        this.account = new AccountNamespace(req);
     }
-    // ─── Static: createAccount ───────────────────────────────────────────────
+    _request(method, path, opts = {}) {
+        return makeRequest(this._baseUrl, this._apiKey, method, path, opts);
+    }
+    // ─── Static: createAccount ─────────────────────────────────────────────────
     /**
      * Create a new AgentLair account and get an API key.
-     *
-     * No existing account or API key needed — this is the bootstrapping method.
-     * **Save the returned `api_key` immediately** — it will not be shown again.
-     *
-     * @param options   Optional name and recovery email
-     * @param baseUrl   Override API base URL (default: https://agentlair.dev)
+     * No existing account needed. **Save the returned `api_key` immediately** — not shown again.
      *
      * @example
-     * const { api_key, account_id } = await AgentLairClient.createAccount({ name: 'my-agent' });
-     * // Store api_key securely — never log it
-     * const client = new AgentLairClient({ apiKey: api_key });
+     * const { api_key } = await AgentLair.createAccount({ name: 'my-agent' });
+     * const lair = new AgentLair(api_key);
      */
     static async createAccount(options = {}, baseUrl = DEFAULT_BASE_URL) {
         const url = baseUrl.replace(/\/$/, '') + '/v1/auth/keys';
@@ -165,77 +441,58 @@ export class AgentLairClient {
         }
         return data;
     }
-    // ─── Email: claimAddress ─────────────────────────────────────────────────
-    /**
-     * Claim an @agentlair.dev email address for this account.
-     *
-     * First-touch ownership model — the first agent to claim an address owns it.
-     * DKIM, SPF, and DMARC are pre-configured. Ready to send in under 5 seconds.
-     *
-     * Optionally provide a `public_key` (base64url X25519, 32 bytes) to enable
-     * end-to-end encryption for inbound messages.
-     *
-     * @example
-     * await client.claimAddress({ address: 'my-agent@agentlair.dev' });
-     */
+}
+// ─── AgentLairClient (legacy — fully backward compatible) ─────────────────────
+/**
+ * @deprecated Use `AgentLair` instead — simpler string constructor, same namespaces.
+ * `AgentLairClient` is fully retained for backward compatibility.
+ */
+export class AgentLairClient {
+    _apiKey;
+    _baseUrl;
+    /** Vault: put / get / list / delete */
+    vault;
+    /** Email: claim / inbox / send / read / outbox / addresses / webhooks */
+    email;
+    /** Stacks: create / list */
+    stacks;
+    /** Observations: write / read / topics */
+    observations;
+    /** Account: me / usage / billing */
+    account;
+    constructor(options) {
+        this._apiKey = options.apiKey;
+        this._baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, '');
+        const req = this._request.bind(this);
+        this.vault = new VaultNamespace(req);
+        this.email = new EmailNamespace(req);
+        this.stacks = new StacksNamespace(req);
+        this.observations = new ObservationsNamespace(req);
+        this.account = new AccountNamespace(req);
+    }
+    _request(method, path, opts = {}) {
+        return makeRequest(this._baseUrl, this._apiKey, method, path, opts);
+    }
+    /** @deprecated Prefer `AgentLair.createAccount()` */
+    static async createAccount(options = {}, baseUrl = DEFAULT_BASE_URL) {
+        return AgentLair.createAccount(options, baseUrl);
+    }
+    // ─── Legacy flat methods (backward compatible) ────────────────────────────
+    /** @deprecated Use `client.email.claim(address)` */
     async claimAddress(options) {
-        return this._request('POST', '/v1/email/claim', { body: options });
+        return this.email.claim(options.address, { public_key: options.public_key });
     }
-    // ─── Email: sendEmail ────────────────────────────────────────────────────
-    /**
-     * Send a DKIM-signed email from an @agentlair.dev address you own.
-     *
-     * Supports plain text, HTML, or both. Supports threading via `in_reply_to`.
-     * Free tier: 10 emails/day per address.
-     *
-     * @example
-     * await client.sendEmail({
-     *   from: 'my-agent@agentlair.dev',
-     *   to: 'user@example.com',
-     *   subject: 'Hello from AgentLair',
-     *   text: 'Hi! This email was sent by an AI agent.',
-     * });
-     */
+    /** @deprecated Use `client.email.send(options)` */
     async sendEmail(options) {
-        return this._request('POST', '/v1/email/send', { body: options });
+        return this.email.send(options);
     }
-    // ─── Email: getInbox ─────────────────────────────────────────────────────
-    /**
-     * Get the inbox for an @agentlair.dev address you own.
-     *
-     * Returns message previews (no full body). Use `readMessage()` for the full body.
-     *
-     * @example
-     * const { messages, count } = await client.getInbox({ address: 'my-agent@agentlair.dev' });
-     * for (const msg of messages) {
-     *   console.log(msg.from, msg.subject, msg.snippet);
-     * }
-     */
+    /** @deprecated Use `client.email.inbox(address, options)` */
     async getInbox(options) {
-        const query = { address: options.address };
-        if (options.limit !== undefined)
-            query.limit = String(options.limit);
-        return this._request('GET', '/v1/email/inbox', { query });
+        return this.email.inbox(options.address, { limit: options.limit });
     }
-    // ─── Email: readMessage ──────────────────────────────────────────────────
-    /**
-     * Read the full body of a specific message.
-     *
-     * Marks the message as read. For E2E-encrypted messages, returns
-     * `ciphertext` and `ephemeral_public_key` for client-side decryption.
-     *
-     * @param messageId  Use `message_id_url` from inbox (URL-encoded) or raw `message_id`
-     * @param address    The @agentlair.dev address that received the message
-     *
-     * @example
-     * const msg = await client.readMessage({
-     *   messageId: inboxMsg.message_id_url,
-     *   address: 'my-agent@agentlair.dev',
-     * });
-     * console.log(msg.body);
-     */
+    /** @deprecated Use `client.email.read(messageId, address)` */
     async readMessage(options) {
-        return this._request('GET', `/v1/email/messages/${options.messageId}`, { query: { address: options.address } });
+        return this.email.read(options.messageId, options.address);
     }
 }
 //# sourceMappingURL=client.js.map