@xmtp/agent-sdk 1.2.4 → 1.2.5-rc1

package/dist/index.js

@@ -1,5 +1,703 @@
-export { ConsentEntityType, ConsentState, ConversationType, DeliveryStatus, GroupMember, GroupMembershipState, GroupMessageKind, GroupMetadata, GroupPermissions, GroupPermissionsOptions, IdentifierKind, LogLevel, MetadataField, PermissionLevel, PermissionPolicy, PermissionUpdateType, SignatureRequestHandle, SortDirection, } from "@xmtp/node-sdk";
-export { isHexString, validHex } from "@xmtp/node-sdk";
-// Agent SDK
-export * from "./core/index.js";
-//# sourceMappingURL=index.js.map
+import { Dm, Group, contentTypeGroupUpdated, contentTypeReaction, contentTypeReply, contentTypeRemoteAttachment, contentTypeMarkdown, contentTypeReadReceipt, contentTypeText, contentTypeTransactionReference, contentTypeWalletSendCalls, Client, encryptAttachment as encryptAttachment$1, encodeMarkdown, encodeText, isHexString, ApiUrls, DecodedMessage } from '@xmtp/node-sdk';
+export { ConsentEntityType, ConsentState, ConversationType, DeliveryStatus, GroupMember, GroupMembershipState, GroupMessageKind, GroupMetadata, GroupPermissions, GroupPermissionsOptions, IdentifierKind, LogLevel, MetadataField, PermissionLevel, PermissionPolicy, PermissionUpdateType, SignatureRequestHandle, SortDirection, isHexString, validHex } from '@xmtp/node-sdk';
+import EventEmitter from 'node:events';
+import fs from 'node:fs';
+import path from 'node:path';
+import { contentTypesAreEqual } from '@xmtp/content-type-primitives';
+import { toBytes, createWalletClient, http } from 'viem';
+import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';
+import { sepolia } from 'viem/chains';
+
+const fromSelf = (message, client) => {
+    return message.senderInboxId === client.inboxId;
+};
+const hasContent = (message) => {
+    return message.content !== undefined && message.content !== null;
+};
+const isDM = (conversation) => {
+    return conversation instanceof Dm;
+};
+const isGroup = (conversation) => {
+    return conversation instanceof Group;
+};
+const isGroupAdmin = (conversation, message) => {
+    if (isGroup(conversation)) {
+        return conversation.isAdmin(message.senderInboxId);
+    }
+    return false;
+};
+const isGroupSuperAdmin = (conversation, message) => {
+    if (isGroup(conversation)) {
+        return conversation.isSuperAdmin(message.senderInboxId);
+    }
+    return false;
+};
+const isGroupUpdate = (message) => {
+    return contentTypesAreEqual(message.contentType, contentTypeGroupUpdated());
+};
+const isReaction = (message) => {
+    return contentTypesAreEqual(message.contentType, contentTypeReaction());
+};
+const isReply = (message) => {
+    return contentTypesAreEqual(message.contentType, contentTypeReply());
+};
+const isRemoteAttachment = (message) => {
+    return contentTypesAreEqual(message.contentType, contentTypeRemoteAttachment());
+};
+const isMarkdown = (message) => {
+    return contentTypesAreEqual(message.contentType, contentTypeMarkdown());
+};
+const isReadReceipt = (message) => {
+    return contentTypesAreEqual(message.contentType, contentTypeReadReceipt());
+};
+const isText = (message) => {
+    return contentTypesAreEqual(message.contentType, contentTypeText());
+};
+const isTextReply = (message) => {
+    return isReply(message) && typeof message.content.content === "string";
+};
+const isTransactionReference = (message) => {
+    return contentTypesAreEqual(message.contentType, contentTypeTransactionReference());
+};
+const isWalletSendCalls = (message) => {
+    return contentTypesAreEqual(message.contentType, contentTypeWalletSendCalls());
+};
+const usesCodec = (message, codecClass) => {
+    return contentTypesAreEqual(message.contentType, new codecClass().contentType);
+};
+const filter = {
+    fromSelf,
+    hasContent,
+    isDM,
+    isGroup,
+    isGroupAdmin,
+    isGroupSuperAdmin,
+    isGroupUpdate,
+    isMarkdown,
+    isReaction,
+    isReadReceipt,
+    isRemoteAttachment,
+    isReply,
+    isText,
+    isTextReply,
+    isTransactionReference,
+    isWalletSendCalls,
+    usesCodec,
+};
+const f = filter;
+
+const getInstallationInfo = async (client) => {
+    const myInboxId = client.inboxId;
+    const myInstallationId = client.installationId;
+    const inboxStates = await Client.fetchInboxStates([myInboxId], client.options?.env);
+    const installations = inboxStates.find((state) => state.inboxId === myInboxId)?.installations ||
+        [];
+    const sortedInstallations = [...installations].sort((a, b) => {
+        const aTime = a.clientTimestampNs ?? 0n;
+        const bTime = b.clientTimestampNs ?? 0n;
+        return bTime > aTime ? 1 : bTime < aTime ? -1 : 0;
+    });
+    const mostRecentInstallation = sortedInstallations[0];
+    const myInstallationIdHex = Buffer.from(client.installationIdBytes).toString("hex");
+    const info = {
+        totalInstallations: installations.length,
+        installationId: myInstallationId,
+        mostRecentInstallationId: null,
+        isMostRecent: false,
+    };
+    if (mostRecentInstallation) {
+        const mostRecentIdHex = Buffer.from(mostRecentInstallation.bytes).toString("hex");
+        info.mostRecentInstallationId = mostRecentIdHex;
+        info.isMostRecent = myInstallationIdHex === mostRecentIdHex;
+    }
+    return info;
+};
+
+const createUser = (key, chain = sepolia) => {
+    const accountKey = key ?? generatePrivateKey();
+    const account = privateKeyToAccount(accountKey);
+    return {
+        key: accountKey,
+        account,
+        wallet: createWalletClient({
+            account,
+            chain,
+            transport: http(),
+        }),
+    };
+};
+const createIdentifier = (user) => ({
+    identifier: user.account.address.toLowerCase(),
+    identifierKind: 0 /* IdentifierKind.Ethereum */,
+});
+const createSigner = (user) => {
+    const identifier = createIdentifier(user);
+    return {
+        type: "EOA",
+        getIdentifier: () => identifier,
+        signMessage: async (message) => {
+            const signature = await user.wallet.signMessage({
+                account: user.account,
+                message,
+            });
+            return toBytes(signature);
+        },
+    };
+};
+
+class AgentError extends Error {
+    #code;
+    constructor(code, message, cause) {
+        super(message, { cause });
+        this.#code = code;
+    }
+    get code() {
+        return this.#code;
+    }
+}
+class AgentStreamingError extends AgentError {
+}
+
+class ClientContext {
+    #client;
+    constructor({ client }) {
+        this.#client = client;
+    }
+    getClientAddress() {
+        return this.#client.accountIdentifier?.identifier;
+    }
+    get client() {
+        return this.#client;
+    }
+}
+
+/**
+ * Encrypts an attachment for secure remote storage.
+ *
+ * @param attachmentData - The attachment to encrypt, including its data, filename, and MIME type
+ * @returns A promise that resolves with the encrypted attachment containing the encrypted content and metadata
+ */
+function encryptAttachment(attachmentData) {
+    const encryptedAttachment = encryptAttachment$1(attachmentData);
+    return {
+        content: encryptedAttachment,
+        mimeType: attachmentData.mimeType,
+    };
+}
+/**
+ * Creates a remote attachment object from an encrypted attachment and file URL.
+ *
+ * @param encryptedAttachment - The encrypted attachment containing encryption keys and metadata
+ * @param fileUrl - The URL where the encrypted attachment can be downloaded
+ * @returns A remote attachment object with all necessary metadata for retrieval and decryption
+ */
+function createRemoteAttachment(encryptedAttachment, fileUrl) {
+    const url = new URL(fileUrl);
+    return {
+        url: url.toString(),
+        contentDigest: encryptedAttachment.content.contentDigest,
+        salt: encryptedAttachment.content.salt,
+        nonce: encryptedAttachment.content.nonce,
+        secret: encryptedAttachment.content.secret,
+        scheme: url.protocol,
+        contentLength: encryptedAttachment.content.payload.length,
+        filename: encryptedAttachment.content.filename,
+    };
+}
+/**
+ * Creates a remote attachment from a file by encrypting it and uploading it to a remote storage.
+ * This is a convenience function that combines file processing, encryption, uploading, and
+ * remote attachment creation into a single operation.
+ *
+ * @param unencryptedFile - The unencrypted file to process and upload
+ * @param uploadCallback - A callback function that receives the encrypted attachment and returns the URL where it was uploaded
+ * @returns A promise that resolves with a remote attachment containing all necessary metadata for retrieval and decryption
+ */
+async function createRemoteAttachmentFromFile(unencryptedFile, uploadCallback) {
+    const arrayBuffer = await unencryptedFile.arrayBuffer();
+    const attachment = new Uint8Array(arrayBuffer);
+    const attachmentData = {
+        content: attachment,
+        filename: unencryptedFile.name,
+        mimeType: unencryptedFile.type,
+    };
+    const encryptedAttachment = encryptAttachment(attachmentData);
+    const fileUrl = await uploadCallback(encryptedAttachment);
+    return createRemoteAttachment(encryptedAttachment, fileUrl);
+}
+
+class ConversationContext extends ClientContext {
+    #conversation;
+    constructor({ conversation, client, }) {
+        super({ client });
+        this.#conversation = conversation;
+    }
+    isDm() {
+        return filter.isDM(this.#conversation);
+    }
+    isGroup() {
+        return filter.isGroup(this.#conversation);
+    }
+    // Send methods, which don't need a message context, are in ConversationContext to make them available in both dm and group event handlers
+    async sendMarkdown(markdown) {
+        await this.#conversation.sendMarkdown(markdown);
+    }
+    async sendText(text) {
+        await this.#conversation.sendText(text);
+    }
+    async sendRemoteAttachment(unencryptedFile, uploadCallback) {
+        const remoteAttachment = await createRemoteAttachmentFromFile(unencryptedFile, uploadCallback);
+        await this.#conversation.sendRemoteAttachment(remoteAttachment);
+    }
+    get conversation() {
+        return this.#conversation;
+    }
+    get isAllowed() {
+        return this.#conversation.consentState() === 1 /* ConsentState.Allowed */;
+    }
+    get isDenied() {
+        return this.#conversation.consentState() === 2 /* ConsentState.Denied */;
+    }
+    get isUnknown() {
+        return this.#conversation.consentState() === 0 /* ConsentState.Unknown */;
+    }
+}
+
+class MessageContext extends ConversationContext {
+    #message;
+    constructor({ message, conversation, client, }) {
+        super({ conversation, client });
+        this.#message = message;
+    }
+    usesCodec(codecClass) {
+        return filter.usesCodec(this.#message, codecClass);
+    }
+    isMarkdown() {
+        return filter.isMarkdown(this.#message);
+    }
+    isText() {
+        return filter.isText(this.#message);
+    }
+    isReply() {
+        return filter.isReply(this.#message);
+    }
+    isReaction() {
+        return filter.isReaction(this.#message);
+    }
+    isReadReceipt() {
+        return filter.isReadReceipt(this.#message);
+    }
+    isRemoteAttachment() {
+        return filter.isRemoteAttachment(this.#message);
+    }
+    isTransactionReference() {
+        return filter.isTransactionReference(this.#message);
+    }
+    isWalletSendCalls() {
+        return filter.isWalletSendCalls(this.#message);
+    }
+    async sendReaction(content, schema = 1 /* ReactionSchema.Unicode */) {
+        const reaction = {
+            action: 1 /* ReactionAction.Added */,
+            reference: this.#message.id,
+            referenceInboxId: this.#message.senderInboxId,
+            schema,
+            content,
+        };
+        await this.conversation.sendReaction(reaction);
+    }
+    async #sendReply(content) {
+        await this.conversation.sendReply({
+            content,
+            reference: this.#message.id,
+            referenceInboxId: this.#message.senderInboxId,
+        });
+    }
+    async sendMarkdownReply(markdown) {
+        await this.#sendReply(encodeMarkdown(markdown));
+    }
+    async sendTextReply(text) {
+        await this.#sendReply(encodeText(text));
+    }
+    async getSenderAddress() {
+        const inboxState = await this.client.preferences.getInboxStates([
+            this.#message.senderInboxId,
+        ]);
+        return inboxState[0]?.identifiers[0]?.identifier;
+    }
+    get message() {
+        return this.#message;
+    }
+}
+
+class Agent extends EventEmitter {
+    #client;
+    #conversationsStream;
+    #messageStream;
+    #middleware = [];
+    #errorMiddleware = [];
+    #errors = Object.freeze({
+        use: (...errorMiddleware) => {
+            for (const emw of errorMiddleware) {
+                if (Array.isArray(emw)) {
+                    this.#errorMiddleware.push(...emw);
+                }
+                else if (typeof emw === "function") {
+                    this.#errorMiddleware.push(emw);
+                }
+            }
+            return this.#errors;
+        },
+    });
+    #defaultErrorHandler = (currentError) => {
+        const emittedError = currentError instanceof Error
+            ? currentError
+            : new AgentError(9999, `Unhandled error caught by default error middleware.`, currentError);
+        this.emit("unhandledError", emittedError);
+    };
+    #isLocked = false;
+    constructor({ client }) {
+        super();
+        this.#client = client;
+    }
+    static async create(signer, 
+    // Note: we need to omit this so that "Client.create" can correctly infer the codecs.
+    options) {
+        const initializedOptions = { ...(options ?? {}) };
+        initializedOptions.appVersion ??= "agent-sdk/alpha";
+        initializedOptions.disableDeviceSync ??= true;
+        if (process.env.XMTP_FORCE_DEBUG) {
+            const loggingLevel = process.env.XMTP_FORCE_DEBUG_LEVEL || "Warn" /* LogLevel.Warn */;
+            initializedOptions.loggingLevel = loggingLevel;
+            initializedOptions.structuredLogging = true;
+        }
+        const client = await Client.create(signer, {
+            ...initializedOptions,
+            codecs: initializedOptions.codecs,
+        });
+        const info = await getInstallationInfo(client);
+        if (info.totalInstallations > 1 && info.isMostRecent) {
+            console.warn(`[WARNING] You have "${info.totalInstallations}" installations. Installation ID "${info.installationId}" is the most recent. Make sure to persist and reload your installation data. If you exceed the installation limit, your Agent will stop working. Read more: https://docs.xmtp.org/agents/build-agents/local-database#installation-limits-and-revocation-rules`);
+        }
+        return new Agent({ client });
+    }
+    static async createFromEnv(
+    // Note: we need to omit this so that "Client.create" can correctly infer the codecs.
+    options) {
+        const { XMTP_DB_DIRECTORY, XMTP_DB_ENCRYPTION_KEY, XMTP_ENV, XMTP_WALLET_KEY, } = process.env;
+        if (!isHexString(XMTP_WALLET_KEY)) {
+            throw new AgentError(1000, `XMTP_WALLET_KEY env is not in hex (0x) format.`);
+        }
+        const signer = createSigner(createUser(XMTP_WALLET_KEY));
+        const initializedOptions = { ...(options ?? {}) };
+        initializedOptions.dbEncryptionKey =
+            typeof XMTP_DB_ENCRYPTION_KEY === "string"
+                ? isHexString(XMTP_DB_ENCRYPTION_KEY)
+                    ? XMTP_DB_ENCRYPTION_KEY
+                    : `0x${XMTP_DB_ENCRYPTION_KEY}`
+                : undefined;
+        if (XMTP_ENV && Object.keys(ApiUrls).includes(XMTP_ENV)) {
+            initializedOptions.env = XMTP_ENV;
+        }
+        if (typeof XMTP_DB_DIRECTORY === "string") {
+            fs.mkdirSync(XMTP_DB_DIRECTORY, { recursive: true, mode: 0o700 });
+            initializedOptions.dbPath = (inboxId) => {
+                const dbPath = path.join(XMTP_DB_DIRECTORY, `xmtp-${inboxId}.db3`);
+                console.info(`Saving local database to "${dbPath}"`);
+                return dbPath;
+            };
+        }
+        return this.create(signer, initializedOptions);
+    }
+    get libxmtpVersion() {
+        return this.#client.libxmtpVersion;
+    }
+    use(...middleware) {
+        for (const mw of middleware) {
+            if (Array.isArray(mw)) {
+                this.#middleware.push(...mw);
+            }
+            else if (typeof mw === "function") {
+                this.#middleware.push(mw);
+            }
+        }
+        return this;
+    }
+    async #stopStreams() {
+        try {
+            await this.#conversationsStream?.end();
+        }
+        finally {
+            this.#conversationsStream = undefined;
+        }
+        try {
+            await this.#messageStream?.end();
+        }
+        finally {
+            this.#messageStream = undefined;
+        }
+    }
+    /**
+     * Closes all existing streams and restarts the streaming system.
+     */
+    async #handleStreamError(error) {
+        await this.#stopStreams();
+        const recovered = await this.#runErrorChain(error, {
+            client: this.#client,
+        });
+        if (recovered) {
+            this.#isLocked = false;
+            queueMicrotask(() => this.start());
+        }
+    }
+    async start(options) {
+        if (this.#isLocked || this.#conversationsStream || this.#messageStream)
+            return;
+        this.#isLocked = true;
+        try {
+            this.#conversationsStream = await this.#client.conversations.stream({
+                ...options,
+                onValue: async (conversation) => {
+                    try {
+                        if (!conversation) {
+                            return;
+                        }
+                        this.emit("conversation", new ConversationContext({
+                            conversation,
+                            client: this.#client,
+                        }));
+                        if (conversation instanceof Group) {
+                            this.emit("group", new ConversationContext({
+                                conversation,
+                                client: this.#client,
+                            }));
+                        }
+                        else if (conversation instanceof Dm) {
+                            this.emit("dm", new ConversationContext({
+                                conversation,
+                                client: this.#client,
+                            }));
+                        }
+                    }
+                    catch (error) {
+                        const recovered = await this.#runErrorChain(new AgentError(1001, "Emitted value from conversation stream caused an error.", error), new ClientContext({ client: this.#client }));
+                        if (!recovered)
+                            await this.stop();
+                    }
+                },
+                onError: async (error) => {
+                    const recovered = await this.#runErrorChain(new AgentStreamingError(1002, "Error occured during conversation streaming.", error), new ClientContext({ client: this.#client }));
+                    if (!recovered)
+                        await this.stop();
+                },
+            });
+            this.#messageStream = await this.#client.conversations.streamAllMessages({
+                ...options,
+                onValue: async (message) => {
+                    // this case should not happen,
+                    // but we must handle it for proper types
+                    if (!(message instanceof DecodedMessage)) {
+                        return;
+                    }
+                    try {
+                        switch (true) {
+                            case filter.isGroupUpdate(message):
+                                await this.#processMessage(message, "group-update");
+                                break;
+                            case filter.isRemoteAttachment(message):
+                                await this.#processMessage(message, "attachment");
+                                break;
+                            case filter.isReaction(message):
+                                await this.#processMessage(message, "reaction");
+                                break;
+                            case filter.isReadReceipt(message):
+                                await this.#processMessage(message, "read-receipt");
+                                break;
+                            case filter.isReply(message):
+                                await this.#processMessage(message, "reply");
+                                break;
+                            case filter.isTransactionReference(message):
+                                await this.#processMessage(message, "transaction-reference");
+                                break;
+                            case filter.isWalletSendCalls(message):
+                                await this.#processMessage(message, "wallet-send-calls");
+                                break;
+                            case filter.isMarkdown(message):
+                                await this.#processMessage(message, "markdown");
+                                break;
+                            case filter.isText(message):
+                                await this.#processMessage(message, "text");
+                                break;
+                            default:
+                                await this.#processMessage(message);
+                                break;
+                        }
+                    }
+                    catch (error) {
+                        const recovered = await this.#runErrorChain(error, {
+                            client: this.#client,
+                        });
+                        if (!recovered) {
+                            await this.stop();
+                        }
+                        this.#isLocked = false;
+                    }
+                },
+                onError: async (error) => {
+                    const recovered = await this.#runErrorChain(new AgentStreamingError(1004, "Error occured during message streaming.", error), new ClientContext({ client: this.#client }));
+                    if (!recovered)
+                        await this.stop();
+                },
+            });
+            this.emit("start", new ClientContext({ client: this.#client }));
+            this.#isLocked = false;
+        }
+        catch (error) {
+            await this.#handleStreamError(error);
+        }
+    }
+    async #processMessage(message, topic = "unknownMessage") {
+        // Skip messages with undefined content (failed to decode)
+        if (!filter.hasContent(message)) {
+            return;
+        }
+        // Skip messages from agent itself
+        if (filter.fromSelf(message, this.#client)) {
+            return;
+        }
+        const conversation = await this.#client.conversations.getConversationById(message.conversationId);
+        if (!conversation) {
+            throw new AgentError(1003, `Failed to process message ID "${message.id}" for conversation ID "${message.conversationId}" because the conversation could not be found.`);
+        }
+        const context = new MessageContext({
+            message,
+            conversation,
+            client: this.#client,
+        });
+        await this.#runMiddlewareChain(context, topic);
+    }
+    async #runMiddlewareChain(context, topic = "unknownMessage") {
+        const finalEmit = async () => {
+            try {
+                this.emit(topic, context);
+                this.emit("message", context);
+            }
+            catch (error) {
+                await this.#runErrorChain(error, context);
+            }
+        };
+        const chain = this.#middleware.reduceRight((next, mw) => {
+            return async () => {
+                try {
+                    await mw(context, next);
+                }
+                catch (error) {
+                    const resume = await this.#runErrorChain(error, context);
+                    if (resume) {
+                        await next();
+                    }
+                    // Chain is not resuming, error is being swallowed
+                }
+            };
+        }, finalEmit);
+        await chain();
+    }
+    async #runErrorHandler(handler, context, error) {
+        let settled = false;
+        let flow = { kind: "stopped" };
+        const next = (nextErr) => {
+            if (settled)
+                return;
+            settled = true;
+            flow =
+                nextErr === undefined
+                    ? { kind: "handled" }
+                    : { kind: "continue", error: nextErr };
+        };
+        try {
+            await handler(error, context, next);
+            return flow;
+        }
+        catch (thrown) {
+            if (settled) {
+                return flow;
+            }
+            return { kind: "continue", error: thrown };
+        }
+    }
+    async #runErrorChain(error, context) {
+        const chain = [...this.#errorMiddleware, this.#defaultErrorHandler];
+        let currentError = error;
+        for (let i = 0; i < chain.length; i++) {
+            const handler = chain[i];
+            if (!handler)
+                continue;
+            const outcome = await this.#runErrorHandler(handler, context, currentError);
+            switch (outcome.kind) {
+                case "handled":
+                    // Error was handled. Main middleware can continue.
+                    return true;
+                case "stopped":
+                    // Error cannot be handled. Main middleware won't continue.
+                    return false;
+                case "continue":
+                    // Error is passed to the next handler
+                    currentError = outcome.error;
+            }
+        }
+        // Reached end of chain without recovery
+        return false;
+    }
+    get client() {
+        return this.#client;
+    }
+    get errors() {
+        return this.#errors;
+    }
+    async stop() {
+        this.#isLocked = true;
+        await this.#stopStreams();
+        this.emit("stop", new ClientContext({ client: this.#client }));
+        this.#isLocked = false;
+    }
+    createDmWithAddress(address, options) {
+        return this.#client.conversations.createDmWithIdentifier({
+            identifier: address,
+            identifierKind: 0 /* IdentifierKind.Ethereum */,
+        }, options);
+    }
+    createGroupWithAddresses(addresses, options) {
+        const identifiers = addresses.map((address) => {
+            return {
+                identifier: address,
+                identifierKind: 0 /* IdentifierKind.Ethereum */,
+            };
+        });
+        return this.#client.conversations.createGroupWithIdentifiers(identifiers, options);
+    }
+    addMembersWithAddresses(group, addresses) {
+        const identifiers = addresses.map((address) => {
+            return {
+                identifier: address,
+                identifierKind: 0 /* IdentifierKind.Ethereum */,
+            };
+        });
+        return group.addMembersByIdentifiers(identifiers);
+    }
+    async getConversationContext(conversationId) {
+        const conversation = await this.client.conversations.getConversationById(conversationId);
+        if (conversation) {
+            const context = new ConversationContext({
+                conversation,
+                client: this.#client,
+            });
+            return context;
+        }
+    }
+    get address() {
+        return this.#client.accountIdentifier?.identifier;
+    }
+}
+
+export { Agent, AgentError, AgentStreamingError, ClientContext, ConversationContext, MessageContext, f, filter };
+//# sourceMappingURL=index.js.map