@hybrd/xmtp 1.0.0 → 1.0.3

package/dist/src/resolver/xmtp-resolver.d.ts

@@ -0,0 +1,95 @@
+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;
+}
+export declare class XmtpResolver {
+    private client;
+    private addressCache;
+    private messageCache;
+    private readonly maxCacheSize;
+    private readonly cacheTtl;
+    private readonly maxMessageCacheSize;
+    private readonly messageCacheTtl;
+    constructor(client: XmtpClient, options?: XmtpResolverOptions);
+    /**
+     * Resolve user address from inbox ID with caching
+     */
+    resolveAddress(inboxId: string, conversationId?: string): Promise<`0x${string}` | null>;
+    /**
+     * Find any message by ID with caching
+     */
+    findMessage(messageId: string): Promise<XmtpMessage | null>;
+    /**
+     * Find root message with caching
+     */
+    findRootMessage(messageId: string): Promise<XmtpMessage | null>;
+    /**
+     * Recursively finds the root message in a reply chain by following reply references
+     */
+    private findRootMessageRecursive;
+    /**
+     * Resolve address from conversation members
+     */
+    private resolveFromConversation;
+    /**
+     * Resolve address from inbox state (network fallback)
+     */
+    private resolveFromInboxState;
+    /**
+     * Get cached address if not expired
+     */
+    private getCachedAddress;
+    /**
+     * Cache address with LRU eviction
+     */
+    private setCachedAddress;
+    /**
+     * Get cached message if not expired
+     */
+    private getCachedMessage;
+    /**
+     * Cache message with LRU eviction
+     */
+    private setCachedMessage;
+    /**
+     * Pre-populate address cache from existing conversations
+     */
+    prePopulateCache(): Promise<void>;
+    /**
+     * Clear all caches
+     */
+    clearCache(): void;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        address: {
+            size: number;
+            maxSize: number;
+        };
+        message: {
+            size: number;
+            maxSize: number;
+        };
+    };
+}
+export {};

package/dist/src/resolver/xmtp-resolver.js

@@ -0,0 +1,297 @@
+export class XmtpResolver {
+    constructor(client, options = {}) {
+        this.client = client;
+        this.addressCache = new Map();
+        this.messageCache = new Map();
+        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, conversationId) {
+        // 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) {
+        // 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) {
+        // 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
+     */
+    async findRootMessageRecursive(messageId, visitedIds = new Set()) {
+        // 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.content?.reference) {
+            return this.findRootMessageRecursive(message.content.reference, visitedIds);
+        }
+        return message;
+    }
+    /**
+     * Resolve address from conversation members
+     */
+    async resolveFromConversation(conversation, inboxId) {
+        try {
+            const members = await conversation.members();
+            const sender = members.find((member) => member.inboxId.toLowerCase() === inboxId.toLowerCase());
+            if (sender) {
+                const ethIdentifier = sender.accountIdentifiers.find((id) => 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)
+     */
+    async resolveFromInboxState(inboxId) {
+        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;
+            }
+        }
+        catch (error) {
+            console.error(`❌ [XmtpResolver] Error resolving from inbox state:`, error);
+        }
+        return null;
+    }
+    /**
+     * Get cached address if not expired
+     */
+    getCachedAddress(inboxId) {
+        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;
+    }
+    /**
+     * Cache address with LRU eviction
+     */
+    setCachedAddress(inboxId, address) {
+        // 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
+     */
+    getCachedMessage(messageId) {
+        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
+     */
+    setCachedMessage(messageId, message) {
+        // 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() {
+        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) => id.identifierKind === 0 // IdentifierKind.Ethereum
+                        );
+                        if (ethIdentifier) {
+                            this.setCachedAddress(member.inboxId, ethIdentifier.identifier);
+                            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() {
+        this.addressCache.clear();
+        this.messageCache.clear();
+        console.log("🗑️ [XmtpResolver] All caches cleared");
+    }
+    /**
+     * Get cache statistics
+     */
+    getCacheStats() {
+        return {
+            address: {
+                size: this.addressCache.size,
+                maxSize: this.maxCacheSize
+            },
+            message: {
+                size: this.messageCache.size,
+                maxSize: this.maxMessageCacheSize
+            }
+        };
+    }
+}

package/dist/src/service-client.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @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 declare class XmtpServiceClient {
+    private config;
+    constructor(config: XmtpServiceClientConfig);
+    private request;
+    sendMessage(params: SendMessageParams): Promise<XmtpServiceResponse<SendMessageResponse>>;
+    sendReply(params: SendReplyParams): Promise<XmtpServiceResponse<SendReplyResponse>>;
+    sendReaction(params: SendReactionParams): Promise<XmtpServiceResponse<SendReactionResponse>>;
+    sendTransaction(params: SendTransactionParams): Promise<XmtpServiceResponse<SendTransactionResponse>>;
+    /**
+     * Get a single message by ID
+     */
+    getMessage(params: GetMessageParams): Promise<XmtpServiceResponse<XmtpServiceMessage>>;
+}
+/**
+ * Create an XMTP service client from runtime context
+ * Expects the runtime context to have xmtpServiceUrl and xmtpServiceToken
+ */
+export declare function createXmtpServiceClient(serviceUrl: string, serviceToken: string): XmtpServiceClient;
+export interface XmtpAuthConfig {
+    serviceUrl: string;
+    serviceToken: string;
+    source: "callback" | "environment";
+}
+/**
+ * Get XMTP authentication configuration from multiple sources
+ * Priority: callback credentials > environment credentials
+ */
+export declare function getXmtpAuthConfig(callbackUrl?: string, callbackToken?: string): XmtpAuthConfig | null;
+/**
+ * Create an authenticated XMTP service client
+ * Handles both callback and environment credential sources
+ */
+export declare function createAuthenticatedXmtpClient(callbackUrl?: string, callbackToken?: string): XmtpServiceClient;
+/**
+ * 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 declare function getXMTPToolsUrl(baseUrl: string, action: string, token: string): string;

package/dist/src/service-client.js

@@ -0,0 +1,198 @@
+/**
+ * @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.
+ */
+export class XmtpServiceClient {
+    constructor(config) {
+        this.config = config;
+    }
+    async request(endpoint, body, method = "POST") {
+        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 = {
+                "Content-Type": "application/json"
+            };
+            // Add Authorization header for xmtp-tools endpoints
+            if (isXmtpToolsEndpoint) {
+                headers.Authorization = `Bearer ${this.config.serviceToken}`;
+            }
+            const fetchOptions = {
+                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);
+                        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())
+            };
+        }
+        catch (error) {
+            console.error(`❌ [XmtpServiceClient] Request to ${endpoint} failed:`, error);
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : "Unknown error"
+            };
+        }
+    }
+    async sendMessage(params) {
+        return this.request("/xmtp-tools/send", {
+            content: params.content
+        });
+    }
+    async sendReply(params) {
+        return this.request("/xmtp-tools/reply", {
+            content: params.content,
+            messageId: params.messageId
+        });
+    }
+    async sendReaction(params) {
+        return this.request("/xmtp-tools/react", {
+            messageId: params.messageId,
+            emoji: params.emoji,
+            action: params.action
+        });
+    }
+    async sendTransaction(params) {
+        return this.request("/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) {
+        return this.request(`/xmtp-tools/messages/${params.messageId}`, undefined, "GET");
+    }
+}
+/**
+ * Create an XMTP service client from runtime context
+ * Expects the runtime context to have xmtpServiceUrl and xmtpServiceToken
+ */
+export function createXmtpServiceClient(serviceUrl, serviceToken) {
+    if (!serviceUrl || !serviceToken) {
+        throw new Error("Missing XMTP service URL or token from runtime context");
+    }
+    return new XmtpServiceClient({
+        serviceUrl,
+        serviceToken
+    });
+}
+/**
+ * Get XMTP authentication configuration from multiple sources
+ * Priority: callback credentials > environment credentials
+ */
+export function getXmtpAuthConfig(callbackUrl, callbackToken) {
+    // 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, callbackToken) {
+    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, action, token) {
+    return `${baseUrl}/xmtp-tools/${action}?token=${token}`;
+}