agentwallet-sdk 5.0.5 → 5.1.0

package/dist/identity/email-resolver.js

@@ -0,0 +1,283 @@
+/**
+ * EmailResolver — AgentMail integration for agentwallet-sdk.
+ * Gives every agent its own email inbox and resolves emails to wallet addresses.
+ *
+ * AgentMail API: https://api.agentmail.to/v0
+ * Docs: https://docs.agentmail.to
+ */
+
+const DEFAULT_BASE_URL = 'https://api.agentmail.to/v0';
+const DEFAULT_CACHE_TTL = 300; // 5 minutes
+
+// ── x402 payment request format embedded in email bodies ──────────────────────
+const X402_PAYMENT_HEADER = '<!-- x402-payment-request';
+const X402_PAYMENT_FOOTER = 'x402-payment-request -->';
+
+function encodePaymentRequest(req) {
+  return `\n\n${X402_PAYMENT_HEADER}\n${JSON.stringify(req, null, 2)}\n${X402_PAYMENT_FOOTER}\n`;
+}
+
+function parsePaymentRequest(body) {
+  const start = body.indexOf(X402_PAYMENT_HEADER);
+  const end = body.indexOf(X402_PAYMENT_FOOTER);
+  if (start === -1 || end === -1) return undefined;
+  try {
+    const json = body.slice(start + X402_PAYMENT_HEADER.length, end).trim();
+    return JSON.parse(json);
+  } catch {
+    return undefined;
+  }
+}
+
+// ── API client helpers ─────────────────────────────────────────────────────────
+
+async function agentMailRequest(apiKey, baseUrl, method, path, body) {
+  const url = `${baseUrl}${path}`;
+  const opts = {
+    method,
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+    },
+  };
+  if (body !== undefined) {
+    opts.body = JSON.stringify(body);
+  }
+
+  const res = await fetch(url, opts);
+  if (!res.ok) {
+    const text = await res.text().catch(() => '(no body)');
+    throw new Error(`AgentMail API error ${res.status}: ${text}`);
+  }
+  if (res.status === 204) return undefined;
+  return res.json();
+}
+
+// ── Map AgentMail inbox response → AgentInbox ─────────────────────────────────
+
+function mapInbox(raw) {
+  // AgentMail inbox shape: { id, username, domain, display_name, created_at, ... }
+  const email = raw.username && raw.domain
+    ? `${raw.username}@${raw.domain}`
+    : raw.email_address ?? raw.address ?? '';
+  return {
+    emailAddress: email,
+    inboxId: raw.id ?? raw.inbox_id,
+    displayName: raw.display_name ?? raw.displayName ?? '',
+    createdAt: raw.created_at ?? raw.createdAt ?? new Date().toISOString(),
+  };
+}
+
+// ── Map AgentMail message response → AgentEmail ───────────────────────────────
+
+function mapMessage(raw) {
+  const body = raw.body?.text ?? raw.text ?? raw.body ?? '';
+  return {
+    messageId: raw.id ?? raw.message_id,
+    from: raw.from ?? raw.sender ?? '',
+    to: Array.isArray(raw.to) ? raw.to : [raw.to ?? ''],
+    subject: raw.subject ?? '',
+    body,
+    timestamp: raw.timestamp ?? raw.received_at ?? raw.created_at ?? '',
+    threadId: raw.thread_id ?? raw.threadId,
+    paymentRequest: parsePaymentRequest(body),
+  };
+}
+
+// ── EmailResolver class ───────────────────────────────────────────────────────
+
+export class EmailResolver {
+  constructor(config) {
+    if (!config?.agentMailApiKey) {
+      throw new Error('EmailResolver: agentMailApiKey is required');
+    }
+    this.apiKey = config.agentMailApiKey;
+    this.baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
+    this.cacheTtl = config.cacheTtlSeconds ?? DEFAULT_CACHE_TTL;
+    this.cache = new Map();
+  }
+
+  // ── Inbox management ────────────────────────────────────────────────────────
+
+  async createInbox({ agentName, displayName, walletAddress, chain = 'base' }) {
+    if (!agentName) throw new Error('agentName is required');
+    if (!walletAddress) throw new Error('walletAddress is required');
+
+    // AgentMail inbox creation — username becomes the local part of the email
+    const raw = await agentMailRequest(this.apiKey, this.baseUrl, 'POST', '/inboxes', {
+      username: agentName.toLowerCase().replace(/[^a-z0-9-]/g, '-'),
+      display_name: displayName,
+      // Store wallet metadata in AgentMail's custom fields
+      metadata: {
+        wallet_address: walletAddress,
+        chain,
+        sdk: 'agentwallet-sdk',
+      },
+    });
+
+    return mapInbox(raw);
+  }
+
+  async listInboxes() {
+    const data = await agentMailRequest(this.apiKey, this.baseUrl, 'GET', '/inboxes');
+    const items = data?.inboxes ?? data?.items ?? (Array.isArray(data) ? data : []);
+    return items.map(mapInbox);
+  }
+
+  async getInbox(inboxId) {
+    const raw = await agentMailRequest(this.apiKey, this.baseUrl, 'GET', `/inboxes/${inboxId}`);
+    return mapInbox(raw);
+  }
+
+  async deleteInbox(inboxId) {
+    await agentMailRequest(this.apiKey, this.baseUrl, 'DELETE', `/inboxes/${inboxId}`);
+  }
+
+  // ── Email ↔ Wallet resolution ───────────────────────────────────────────────
+
+  async resolveEmailToWallet(emailAddress) {
+    const normalised = emailAddress.toLowerCase().trim();
+
+    // 1. Cache hit
+    const cached = this.cache.get(normalised);
+    if (cached && Date.now() / 1000 - cached.resolvedAt < this.cacheTtl) {
+      return cached;
+    }
+
+    // 2. AgentMail lookup — scan inboxes for matching email + wallet metadata
+    try {
+      const inboxes = await this.listInboxes();
+      for (const inbox of inboxes) {
+        if (inbox.emailAddress.toLowerCase() === normalised) {
+          // Fetch full inbox to get metadata
+          const full = await agentMailRequest(
+            this.apiKey, this.baseUrl, 'GET', `/inboxes/${inbox.inboxId}`
+          );
+          const walletAddress = full?.metadata?.wallet_address;
+          const chain = full?.metadata?.chain ?? 'base';
+          if (walletAddress) {
+            const resolution = {
+              emailAddress: normalised,
+              walletAddress,
+              chain,
+              source: 'agentmail',
+              resolvedAt: Math.floor(Date.now() / 1000),
+            };
+            this.cache.set(normalised, resolution);
+            return resolution;
+          }
+        }
+      }
+    } catch (err) {
+      // Fall through to ENS
+    }
+
+    // 3. ENS fallback — resolve agent.eth-style names
+    // e.g., agent@ens.agentmail.to → agent.eth
+    if (normalised.includes('@ens.')) {
+      const localPart = normalised.split('@')[0];
+      const ensName = `${localPart}.eth`;
+      // ENS resolution requires viem — import dynamically to avoid hard dep
+      try {
+        const { createPublicClient, http } = await import('viem');
+        const { mainnet } = await import('viem/chains');
+        const client = createPublicClient({ chain: mainnet, transport: http() });
+        const addr = await client.getEnsAddress({ name: ensName });
+        if (addr) {
+          const resolution = {
+            emailAddress: normalised,
+            walletAddress: addr,
+            chain: 'ethereum',
+            source: 'ens',
+            resolvedAt: Math.floor(Date.now() / 1000),
+          };
+          this.cache.set(normalised, resolution);
+          return resolution;
+        }
+      } catch {
+        // ENS lookup failed
+      }
+    }
+
+    throw new Error(`EmailResolver: could not resolve wallet for ${emailAddress}`);
+  }
+
+  async resolveWalletToEmail(walletAddress) {
+    const normalised = walletAddress.toLowerCase().trim();
+    try {
+      const inboxes = await this.listInboxes();
+      for (const inbox of inboxes) {
+        const full = await agentMailRequest(
+          this.apiKey, this.baseUrl, 'GET', `/inboxes/${inbox.inboxId}`
+        );
+        if (full?.metadata?.wallet_address?.toLowerCase() === normalised) {
+          return inbox.emailAddress;
+        }
+      }
+    } catch {
+      // ignore
+    }
+    return null;
+  }
+
+  // ── Messaging ───────────────────────────────────────────────────────────────
+
+  async fetchMessages(inboxId, options = {}) {
+    const params = new URLSearchParams();
+    if (options.unreadOnly) params.set('unread', 'true');
+    if (options.limit) params.set('limit', String(options.limit));
+    if (options.threadId) params.set('thread_id', options.threadId);
+
+    const qs = params.toString();
+    const path = `/inboxes/${inboxId}/messages${qs ? `?${qs}` : ''}`;
+    const data = await agentMailRequest(this.apiKey, this.baseUrl, 'GET', path);
+    const items = data?.messages ?? data?.items ?? (Array.isArray(data) ? data : []);
+    return items.map(mapMessage);
+  }
+
+  async sendEmail({ inboxId, to, subject, body, paymentRequest, replyToMessageId }) {
+    const recipients = Array.isArray(to) ? to : [to];
+    let fullBody = body;
+    if (paymentRequest) {
+      fullBody += encodePaymentRequest(paymentRequest);
+    }
+
+    const payload = {
+      to: recipients,
+      subject,
+      body: { text: fullBody },
+    };
+    if (replyToMessageId) {
+      payload.reply_to_message_id = replyToMessageId;
+    }
+
+    const result = await agentMailRequest(
+      this.apiKey, this.baseUrl, 'POST', `/inboxes/${inboxId}/messages`, payload
+    );
+    return { messageId: result?.id ?? result?.message_id };
+  }
+
+  async replyToEmail({ inboxId, messageId, body, paymentRequest }) {
+    let fullBody = body;
+    if (paymentRequest) {
+      fullBody += encodePaymentRequest(paymentRequest);
+    }
+    const result = await agentMailRequest(
+      this.apiKey, this.baseUrl, 'POST', `/inboxes/${inboxId}/messages/${messageId}/reply`,
+      { body: { text: fullBody } }
+    );
+    return { messageId: result?.id ?? result?.message_id };
+  }
+
+  async markAsRead(inboxId, messageId) {
+    await agentMailRequest(
+      this.apiKey, this.baseUrl, 'PATCH', `/inboxes/${inboxId}/messages/${messageId}`,
+      { read: true }
+    );
+  }
+
+  clearCache() {
+    this.cache.clear();
+  }
+}