@hybrd/xmtp 1.0.0

package/src/resolver/xmtp-resolver.ts

@@ -0,0 +1,436 @@
+import type { XmtpClient, XmtpMessage } from "../types"
+
+interface XmtpResolverOptions {
+	/**
+	 * Maximum number of addresses to cache
+	 * @default 1000
+	 */
+	maxCacheSize?: number
+	/**
+	 * Cache TTL in milliseconds
+	 * @default 86400000 (24 hours)
+	 */
+	cacheTtl?: number
+	/**
+	 * Maximum number of messages to cache
+	 * @default 1000
+	 */
+	maxMessageCacheSize?: number
+	/**
+	 * Message cache TTL in milliseconds
+	 * @default 3600000 (1 hour)
+	 */
+	messageCacheTtl?: number
+}
+
+interface AddressCacheEntry {
+	address: string
+	timestamp: number
+}
+
+interface MessageCacheEntry {
+	message: XmtpMessage | null
+	timestamp: number
+}
+
+export class XmtpResolver {
+	private addressCache = new Map<string, AddressCacheEntry>()
+	private messageCache = new Map<string, MessageCacheEntry>()
+	private readonly maxCacheSize: number
+	private readonly cacheTtl: number
+	private readonly maxMessageCacheSize: number
+	private readonly messageCacheTtl: number
+
+	constructor(
+		private client: XmtpClient,
+		options: XmtpResolverOptions = {}
+	) {
+		this.maxCacheSize = options.maxCacheSize ?? 1000
+		this.cacheTtl = options.cacheTtl ?? 86400000 // 24 hours
+		this.maxMessageCacheSize = options.maxMessageCacheSize ?? 1000
+		this.messageCacheTtl = options.messageCacheTtl ?? 3600000 // 1 hour
+	}
+
+	/**
+	 * Resolve user address from inbox ID with caching
+	 */
+	async resolveAddress(
+		inboxId: string,
+		conversationId?: string
+	): Promise<`0x${string}` | null> {
+		// Check cache first (fastest)
+		const cached = this.getCachedAddress(inboxId)
+		if (cached) {
+			console.log(
+				`✅ [XmtpResolver] Resolved user address from cache: ${cached}`
+			)
+			return cached
+		}
+
+		let userAddress = undefined
+
+		try {
+			// Try conversation members lookup first (faster than network call)
+			if (conversationId) {
+				const conversation =
+					await this.client.conversations.getConversationById(conversationId)
+				if (conversation) {
+					userAddress = await this.resolveFromConversation(
+						conversation,
+						inboxId
+					)
+					if (userAddress) {
+						this.setCachedAddress(inboxId, userAddress)
+						console.log(
+							`✅ [XmtpResolver] Resolved user address: ${userAddress}`
+						)
+						return userAddress
+					}
+				}
+			}
+
+			// Fallback to inboxStateFromInboxIds
+			userAddress = await this.resolveFromInboxState(inboxId)
+			if (userAddress) {
+				this.setCachedAddress(inboxId, userAddress)
+				console.log(
+					`✅ [XmtpResolver] Resolved user address via fallback: ${userAddress}`
+				)
+				return userAddress
+			}
+
+			console.log(`⚠️ [XmtpResolver] No identifiers found for inbox ${inboxId}`)
+			return null
+		} catch (error) {
+			console.error(
+				`❌ [XmtpResolver] Error resolving user address for ${inboxId}:`,
+				error
+			)
+			return null
+		}
+	}
+
+	/**
+	 * Find any message by ID with caching
+	 */
+	async findMessage(messageId: string): Promise<XmtpMessage | null> {
+		// Check cache first
+		const cached = this.getCachedMessage(messageId)
+		if (cached !== undefined) {
+			console.log(
+				cached
+					? `✅ [XmtpResolver] Found message from cache: ${cached.id}`
+					: `✅ [XmtpResolver] Found cached null message for: ${messageId}`
+			)
+			return cached
+		}
+
+		try {
+			console.log(`🔍 [XmtpResolver] Finding message: ${messageId}`)
+			const message = await this.client.conversations.getMessageById(messageId)
+
+			if (message) {
+				this.setCachedMessage(messageId, message)
+				console.log(`✅ [XmtpResolver] Found and cached message: ${message.id}`)
+				return message
+			}
+
+			console.log(`⚠️ [XmtpResolver] Message not found: ${messageId}`)
+			this.setCachedMessage(messageId, null)
+			return null
+		} catch (error) {
+			console.error(
+				`❌ [XmtpResolver] Error finding message ${messageId}:`,
+				error
+			)
+			this.setCachedMessage(messageId, null)
+			return null
+		}
+	}
+
+	/**
+	 * Find root message with caching
+	 */
+	async findRootMessage(messageId: string): Promise<XmtpMessage | null> {
+		// Check if we already have the root cached with a special key
+		const rootCacheKey = `root:${messageId}`
+		const cached = this.getCachedMessage(rootCacheKey)
+		if (cached !== undefined) {
+			console.log(
+				cached
+					? `✅ [XmtpResolver] Found root message from cache: ${cached.id}`
+					: `✅ [XmtpResolver] Found cached null root for: ${messageId}`
+			)
+			return cached
+		}
+
+		try {
+			console.log(`🔍 [XmtpResolver] Finding root message for: ${messageId}`)
+			const rootMessage = await this.findRootMessageRecursive(messageId)
+
+			if (rootMessage) {
+				this.setCachedMessage(rootCacheKey, rootMessage)
+				console.log(
+					`✅ [XmtpResolver] Found and cached root message: ${rootMessage.id}`
+				)
+				return rootMessage
+			}
+
+			console.log(`⚠️ [XmtpResolver] No root message found for: ${messageId}`)
+			this.setCachedMessage(rootCacheKey, null)
+			return null
+		} catch (error) {
+			console.error(
+				`❌ [XmtpResolver] Error finding root message for ${messageId}:`,
+				error
+			)
+			this.setCachedMessage(rootCacheKey, null)
+			return null
+		}
+	}
+
+	/**
+	 * Recursively finds the root message in a reply chain by following reply references
+	 */
+	private async findRootMessageRecursive(
+		messageId: string,
+		visitedIds = new Set<string>()
+	): Promise<XmtpMessage | null> {
+		// Prevent infinite loops
+		if (visitedIds.has(messageId)) {
+			console.warn(
+				`⚠️ Circular reference detected in message chain at ${messageId}`
+			)
+			return null
+		}
+		visitedIds.add(messageId)
+
+		const message = await this.client.conversations.getMessageById(messageId)
+
+		if (!message) {
+			console.warn(`⚠️ [findRootMessage] Message not found: ${messageId}`)
+			return null
+		}
+
+		// Debug: Log the raw message structure as returned by XMTP client
+		console.log(`🔍 [findRootMessage] Raw message ${messageId}:`, {
+			id: message.id,
+			contentType: message.contentType,
+			content: message.content,
+			sentAt: message.sentAt
+		})
+
+		// Method 1: Try the parameters (as seen in webhook data)
+		if ((message as any).content?.reference) {
+			return this.findRootMessageRecursive(
+				(message as any).content.reference,
+				visitedIds
+			)
+		}
+
+		return message
+	}
+
+	/**
+	 * Resolve address from conversation members
+	 */
+	private async resolveFromConversation(
+		conversation: any,
+		inboxId: string
+	): Promise<`0x${string}` | null> {
+		try {
+			const members = await conversation.members()
+			const sender = members.find(
+				(member: any) => member.inboxId.toLowerCase() === inboxId.toLowerCase()
+			)
+
+			if (sender) {
+				const ethIdentifier = sender.accountIdentifiers.find(
+					(id: any) => id.identifierKind === 0 // IdentifierKind.Ethereum
+				)
+				if (ethIdentifier) {
+					return ethIdentifier.identifier
+				} else {
+					console.log(
+						`⚠️ [XmtpResolver] No Ethereum identifier found for inbox ${inboxId}`
+					)
+				}
+			} else {
+				console.log(
+					`⚠️ [XmtpResolver] Sender not found in conversation members for inbox ${inboxId}`
+				)
+			}
+		} catch (error) {
+			console.error(
+				`❌ [XmtpResolver] Error resolving from conversation members:`,
+				error
+			)
+		}
+
+		return null
+	}
+
+	/**
+	 * Resolve address from inbox state (network fallback)
+	 */
+	private async resolveFromInboxState(
+		inboxId: string
+	): Promise<`0x${string}` | null> {
+		try {
+			const inboxState = await this.client.preferences.inboxStateFromInboxIds([
+				inboxId
+			])
+			const firstState = inboxState?.[0]
+			if (firstState?.identifiers && firstState.identifiers.length > 0) {
+				const firstIdentifier = firstState.identifiers[0]
+				return firstIdentifier?.identifier as `0x${string}`
+			}
+		} catch (error) {
+			console.error(
+				`❌ [XmtpResolver] Error resolving from inbox state:`,
+				error
+			)
+		}
+
+		return null
+	}
+
+	/**
+	 * Get cached address if not expired
+	 */
+	private getCachedAddress(inboxId: string): `0x${string}` | null {
+		const entry = this.addressCache.get(inboxId)
+		if (!entry) return null
+
+		const now = Date.now()
+		if (now - entry.timestamp > this.cacheTtl) {
+			this.addressCache.delete(inboxId)
+			return null
+		}
+
+		return entry.address as `0x${string}`
+	}
+
+	/**
+	 * Cache address with LRU eviction
+	 */
+	private setCachedAddress(inboxId: string, address: `0x${string}`): void {
+		// Simple LRU: if cache is full, remove oldest entry
+		if (this.addressCache.size >= this.maxCacheSize) {
+			const firstKey = this.addressCache.keys().next().value
+			if (firstKey) {
+				this.addressCache.delete(firstKey)
+			}
+		}
+
+		this.addressCache.set(inboxId, {
+			address,
+			timestamp: Date.now()
+		})
+	}
+
+	/**
+	 * Get cached message if not expired
+	 */
+	private getCachedMessage(messageId: string): XmtpMessage | null | undefined {
+		const entry = this.messageCache.get(messageId)
+		if (!entry) return undefined
+
+		const now = Date.now()
+		if (now - entry.timestamp > this.messageCacheTtl) {
+			this.messageCache.delete(messageId)
+			return undefined
+		}
+
+		return entry.message
+	}
+
+	/**
+	 * Cache message with LRU eviction
+	 */
+	private setCachedMessage(
+		messageId: string,
+		message: XmtpMessage | null
+	): void {
+		// Simple LRU: if cache is full, remove oldest entry
+		if (this.messageCache.size >= this.maxMessageCacheSize) {
+			const firstKey = this.messageCache.keys().next().value
+			if (firstKey) {
+				this.messageCache.delete(firstKey)
+			}
+		}
+
+		this.messageCache.set(messageId, {
+			message,
+			timestamp: Date.now()
+		})
+	}
+
+	/**
+	 * Pre-populate address cache from existing conversations
+	 */
+	async prePopulateCache(): Promise<void> {
+		console.log("🔄 [XmtpResolver] Pre-populating address cache...")
+		try {
+			const conversations = await this.client.conversations.list()
+			let cachedCount = 0
+
+			for (const conversation of conversations) {
+				try {
+					const members = await conversation.members()
+					for (const member of members) {
+						const ethIdentifier = member.accountIdentifiers.find(
+							(id: any) => id.identifierKind === 0 // IdentifierKind.Ethereum
+						)
+						if (ethIdentifier) {
+							this.setCachedAddress(
+								member.inboxId,
+								ethIdentifier.identifier as `0x${string}`
+							)
+							cachedCount++
+						}
+					}
+				} catch (error) {
+					console.error(
+						"[XmtpResolver] Error pre-caching conversation members:",
+						error
+					)
+				}
+			}
+
+			console.log(
+				`✅ [XmtpResolver] Pre-cached ${cachedCount} address mappings`
+			)
+		} catch (error) {
+			console.error("[XmtpResolver] Error pre-populating cache:", error)
+		}
+	}
+
+	/**
+	 * Clear all caches
+	 */
+	clearCache(): void {
+		this.addressCache.clear()
+		this.messageCache.clear()
+		console.log("🗑️ [XmtpResolver] All caches cleared")
+	}
+
+	/**
+	 * Get cache statistics
+	 */
+	getCacheStats(): {
+		address: { size: number; maxSize: number }
+		message: { size: number; maxSize: number }
+	} {
+		return {
+			address: {
+				size: this.addressCache.size,
+				maxSize: this.maxCacheSize
+			},
+			message: {
+				size: this.messageCache.size,
+				maxSize: this.maxMessageCacheSize
+			}
+		}
+	}
+}

package/src/service-client.ts

@@ -0,0 +1,286 @@
+/**
+ * @fileoverview XMTP Service Client Library
+ *
+ * Clean, reusable client for making HTTP calls to the XMTP listener service.
+ * Handles authentication, request formatting, and error handling.
+ *
+ * This is different from the direct XMTP client - this is for external services
+ * talking to our XMTP listener service.
+ */
+
+import type {
+	GetMessageParams,
+	SendMessageParams,
+	SendMessageResponse,
+	SendReactionParams,
+	SendReactionResponse,
+	SendReplyParams,
+	SendReplyResponse,
+	SendTransactionParams,
+	SendTransactionResponse,
+	XmtpServiceClientConfig,
+	XmtpServiceMessage,
+	XmtpServiceResponse
+} from "./types.js"
+
+export class XmtpServiceClient {
+	private config: XmtpServiceClientConfig
+
+	constructor(config: XmtpServiceClientConfig) {
+		this.config = config
+	}
+
+	private async request<T = unknown>(
+		endpoint: string,
+		body?: Record<string, unknown>,
+		method: "GET" | "POST" = "POST"
+	): Promise<XmtpServiceResponse<T>> {
+		try {
+			const baseUrl = this.config.serviceUrl.replace(/\/+$/, "")
+
+			// Use Authorization header for xmtp-tools endpoints, query parameter for others
+			const isXmtpToolsEndpoint = endpoint.startsWith("/xmtp-tools/")
+			const url = `${baseUrl}${endpoint}?token=${this.config.serviceToken}`
+
+			const headers: Record<string, string> = {
+				"Content-Type": "application/json"
+			}
+
+			// Add Authorization header for xmtp-tools endpoints
+			if (isXmtpToolsEndpoint) {
+				headers.Authorization = `Bearer ${this.config.serviceToken}`
+			}
+
+			const fetchOptions: RequestInit = {
+				method,
+				headers
+			}
+
+			if (method === "POST" && body) {
+				fetchOptions.body = JSON.stringify(body)
+			}
+
+			const response = await fetch(url, fetchOptions)
+
+			if (!response.ok) {
+				let errorMessage = `HTTP ${response.status}`
+				try {
+					const responseText = await response.text()
+					try {
+						const errorData = JSON.parse(responseText) as { error?: string }
+						errorMessage = errorData.error || errorMessage
+					} catch {
+						errorMessage = responseText || errorMessage
+					}
+				} catch {
+					// If we can't read the response at all, use the status
+				}
+				throw new Error(errorMessage)
+			}
+
+			return {
+				success: true,
+				data: (await response.json()) as T
+			}
+		} catch (error) {
+			console.error(
+				`❌ [XmtpServiceClient] Request to ${endpoint} failed:`,
+				error
+			)
+			return {
+				success: false,
+				error: error instanceof Error ? error.message : "Unknown error"
+			}
+		}
+	}
+
+	async sendMessage(
+		params: SendMessageParams
+	): Promise<XmtpServiceResponse<SendMessageResponse>> {
+		return this.request<SendMessageResponse>("/xmtp-tools/send", {
+			content: params.content
+		})
+	}
+
+	async sendReply(
+		params: SendReplyParams
+	): Promise<XmtpServiceResponse<SendReplyResponse>> {
+		return this.request<SendReplyResponse>("/xmtp-tools/reply", {
+			content: params.content,
+			messageId: params.messageId
+		})
+	}
+
+	async sendReaction(
+		params: SendReactionParams
+	): Promise<XmtpServiceResponse<SendReactionResponse>> {
+		return this.request<SendReactionResponse>("/xmtp-tools/react", {
+			messageId: params.messageId,
+			emoji: params.emoji,
+			action: params.action
+		})
+	}
+
+	async sendTransaction(
+		params: SendTransactionParams
+	): Promise<XmtpServiceResponse<SendTransactionResponse>> {
+		return this.request<SendTransactionResponse>("/xmtp-tools/transaction", {
+			fromAddress: params.fromAddress,
+			chainId: params.chainId,
+			calls: params.calls.map((call) => ({
+				to: call.to,
+				data: call.data,
+				...(call.gas && { gas: call.gas }),
+				value: call.value || "0x0",
+				metadata: {
+					...call.metadata,
+					chainId: params.chainId,
+					from: params.fromAddress,
+					version: "1"
+				}
+			}))
+		})
+	}
+
+	/**
+	 * Get a single message by ID
+	 */
+	async getMessage(
+		params: GetMessageParams
+	): Promise<XmtpServiceResponse<XmtpServiceMessage>> {
+		return this.request<XmtpServiceMessage>(
+			`/xmtp-tools/messages/${params.messageId}`,
+			undefined,
+			"GET"
+		)
+	}
+
+	// getConversationMessages removed - superseded by thread-based approach
+}
+
+/**
+ * Create an XMTP service client from runtime context
+ * Expects the runtime context to have xmtpServiceUrl and xmtpServiceToken
+ */
+export function createXmtpServiceClient(
+	serviceUrl: string,
+	serviceToken: string
+): XmtpServiceClient {
+	if (!serviceUrl || !serviceToken) {
+		throw new Error("Missing XMTP service URL or token from runtime context")
+	}
+
+	return new XmtpServiceClient({
+		serviceUrl,
+		serviceToken
+	})
+}
+
+export interface XmtpAuthConfig {
+	serviceUrl: string
+	serviceToken: string
+	source: "callback" | "environment"
+}
+
+/**
+ * Get XMTP authentication configuration from multiple sources
+ * Priority: callback credentials > environment credentials
+ */
+export function getXmtpAuthConfig(
+	callbackUrl?: string,
+	callbackToken?: string
+): XmtpAuthConfig | null {
+	// Priority 1: Use callback credentials if available
+	if (callbackUrl && callbackToken) {
+		console.log("🔑 [XmtpAuth] Using callback-provided credentials")
+		return {
+			serviceUrl: callbackUrl,
+			serviceToken: callbackToken,
+			source: "callback"
+		}
+	}
+
+	// Priority 2: Use environment credentials
+	const envUrl = process.env.XMTP_HOST
+	const envToken = process.env.XMTP_API_KEY
+
+	if (envUrl && envToken) {
+		console.log("🔑 [XmtpAuth] Using environment credentials")
+		return {
+			serviceUrl: envUrl,
+			serviceToken: envToken,
+			source: "environment"
+		}
+	}
+
+	// No valid credentials found
+	console.error(
+		"❌ [XmtpAuth] No XMTP credentials found in callback or environment"
+	)
+	console.error(
+		"💡 [XmtpAuth] Expected: XMTP_HOST + XMTP_API_KEY or callback credentials"
+	)
+	return null
+}
+
+/**
+ * Create an authenticated XMTP service client
+ * Handles both callback and environment credential sources
+ */
+export function createAuthenticatedXmtpClient(
+	callbackUrl?: string,
+	callbackToken?: string
+): XmtpServiceClient {
+	const authConfig = getXmtpAuthConfig(callbackUrl, callbackToken)
+
+	if (!authConfig) {
+		throw new Error("No XMTP credentials found")
+	}
+
+	console.log(
+		`🔗 [XmtpAuth] Creating XMTP client (${authConfig.source} credentials)`
+	)
+
+	return createXmtpServiceClient(authConfig.serviceUrl, authConfig.serviceToken)
+}
+
+/**
+ * Constructs a URL for XMTP tools API endpoints with token authentication
+ *
+ * @param {string} baseUrl - The base URL of the XMTP service (e.g., "https://api.example.com")
+ * @param {string} action - The specific action/endpoint to call (e.g., "send", "receive", "status")
+ * @param {string} token - Authentication token (either JWT or API key)
+ * @returns {string} Complete URL with token as query parameter
+ *
+ * @description
+ * Builds URLs for XMTP tools endpoints using query parameter authentication.
+ * The token is appended as a query parameter for GET request authentication,
+ * following the pattern: `/xmtp-tools/{action}?token={token}`
+ *
+ * @example
+ * ```typescript
+ * const url = getXMTPToolsUrl(
+ *   "https://api.hybrid.dev",
+ *   "send",
+ *   "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+ * );
+ * // Returns: "https://api.hybrid.dev/xmtp-tools/send?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using with API key
+ * const url = getXMTPToolsUrl(
+ *   process.env.XMTP_BASE_URL,
+ *   "status",
+ *   process.env.XMTP_API_KEY
+ * );
+ * ```
+ */
+export function getXMTPToolsUrl(
+	baseUrl: string,
+	action: string,
+	token: string
+): string {
+	return `${baseUrl}/xmtp-tools/${action}?token=${token}`
+}