@xmtp/agent-sdk 2.0.0-rc1 → 2.0.0-rc2

package/README.md

@@ -23,9 +23,7 @@ yarn add @xmtp/agent-sdk
 ## Quick Start
 
 ```ts
-import { Agent } from "@xmtp/agent-sdk";
-import { getTestUrl } from "@xmtp/agent-sdk/debug";
-import { createUser, createSigner } from "@xmtp/agent-sdk/user";
+import { Agent, createUser, createSigner, getTestUrl } from "@xmtp/agent-sdk";
 
 // 1. Create a local user + signer (you can plug in your own wallet signer)
 const user = createUser();
@@ -237,15 +235,14 @@ agent.on("unhandledError", (error) => {
 
 #### Provided Middleware
 
-Built‑in, officially supported middleware is provided via `@xmtp/agent-sdk/middleware`.
+Built‑in, officially supported middleware is provided by the Agent SDK.
 
 **Example: CommandRouter**
 
 The `CommandRouter` makes it easy to handle slash commands out of the box.
 
 ```ts
-import { Agent } from "@xmtp/agent-sdk";
-import { CommandRouter } from "@xmtp/agent-sdk/middleware";
+import { Agent, CommandRouter } from "@xmtp/agent-sdk";
 
 const agent = await Agent.createFromEnv();
 const router = new CommandRouter()
@@ -346,10 +343,10 @@ await group.send("Hello group!");
 
 ### 6. Utilities
 
-The Agent SDK comes with subpackages that include utilities. You can for example get a testing URL or details of your Agent from the debug utilities:
+The Agent SDK includes various utilities. You can for example get a testing URL or details of your Agent:
 
 ```ts
-import { getTestUrl, logDetails } from "@xmtp/agent-sdk/debug";
+import { getTestUrl, logDetails } from "@xmtp/agent-sdk";
 
 // Get a test URL for your agent
 const testUrl = getTestUrl(agent.client);
@@ -362,11 +359,7 @@ await logDetails(agent.client);
 There are also utilities to simplify user management, such as signer creation or name resolutions:
 
 ```ts
-import {
-  createUser,
-  createSigner,
-  createNameResolver,
-} from "@xmtp/agent-sdk/user";
+import { createUser, createSigner, createNameResolver } from "@xmtp/agent-sdk";
 
 // Create a new user with a random private key
 const user = createUser();
@@ -387,7 +380,7 @@ The Agent SDK supports sending encrypted remote attachments. Files are encrypted
 **Example**
 
 ```ts
-import { type AttachmentUploadCallback } from "@xmtp/agent-sdk/util";
+import { type AttachmentUploadCallback } from "@xmtp/agent-sdk";
 
 agent.on("text", async (ctx) => {
   if (ctx.message.content === "/send-file") {
@@ -429,7 +422,7 @@ agent.on("text", async (ctx) => {
 Other agents can then download and decrypt the attachment using the `"attachment"` topic:
 
 ```ts
-import { downloadRemoteAttachment } from "@xmtp/agent-sdk/util";
+import { downloadRemoteAttachment } from "@xmtp/agent-sdk";
 
 agent.on("attachment", async (ctx) => {
   const receivedAttachment = await downloadRemoteAttachment(

package/dist/index.d.ts

@@ -1,4 +1,234 @@
-export { ConsentEntityType, ConsentState, ConversationType, DeliveryStatus, GroupMember, GroupMembershipState, GroupMessageKind, GroupMetadata, GroupPermissions, GroupPermissionsOptions, IdentifierKind, LogLevel, MetadataField, PermissionLevel, PermissionPolicy, PermissionUpdateType, SignatureRequestHandle, SortDirection, } from "@xmtp/node-sdk";
-export type * from "@xmtp/node-sdk";
-export { isHexString, validHex } from "@xmtp/node-sdk";
-export * from "./core/index.js";
+import * as _xmtp_node_sdk from '@xmtp/node-sdk';
+import { Client, EncryptedAttachment, RemoteAttachment, Attachment, Conversation, Dm, Group, DecodedMessage, GroupUpdated, Reaction, ReadReceipt, EnrichedReply, TransactionReference, WalletSendCalls, Reply, StreamOptions, ClientOptions, HexString, CreateDmOptions, CreateGroupOptions, BuiltInContentTypes, Identifier, Signer } from '@xmtp/node-sdk';
+export * from '@xmtp/node-sdk';
+import EventEmitter from 'node:events';
+import { ContentCodec } from '@xmtp/content-type-primitives';
+import { Hex, PrivateKeyAccount, WalletClient, Chain } from 'viem';
+
+declare class ClientContext<ContentTypes = unknown> {
+    #private;
+    constructor({ client }: {
+        client: Client<ContentTypes>;
+    });
+    getClientAddress(): string | undefined;
+    get client(): Client<ContentTypes>;
+}
+
+type AttachmentUploadCallback = (attachment: EncryptedAttachment) => Promise<string>;
+/**
+ * Downloads and decrypts a remote attachment.
+ *
+ * @param remoteAttachment - The remote attachment metadata containing the downloadd URL and encryption keys
+ * @param agent - The agent instance used to lookup the necessary decoding codec
+ * @returns A promise that resolves with the decrypted attachment
+ */
+declare function downloadRemoteAttachment(remoteAttachment: RemoteAttachment): Promise<Attachment>;
+/**
+ * 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
+ */
+declare function createRemoteAttachment(encryptedAttachment: EncryptedAttachment, fileUrl: string): RemoteAttachment;
+/**
+ * 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
+ */
+declare function createRemoteAttachmentFromFile(unencryptedFile: File, uploadCallback: AttachmentUploadCallback): Promise<RemoteAttachment>;
+
+declare class ConversationContext<ContentTypes = unknown, ConversationType extends Conversation = Conversation> extends ClientContext<ContentTypes> {
+    #private;
+    constructor({ conversation, client, }: {
+        conversation: ConversationType;
+        client: Client<ContentTypes>;
+    });
+    isDm(): this is ConversationContext<ContentTypes, Dm<ContentTypes>>;
+    isGroup(): this is ConversationContext<ContentTypes, Group<ContentTypes>>;
+    sendRemoteAttachment(unencryptedFile: File, uploadCallback: AttachmentUploadCallback): Promise<void>;
+    get conversation(): ConversationType;
+    get isAllowed(): boolean;
+    get isDenied(): boolean;
+    get isUnknown(): boolean;
+}
+
+type DecodedMessageWithContent<ContentTypes = unknown> = DecodedMessage<ContentTypes> & {
+    content: ContentTypes;
+};
+declare const filter: {
+    fromSelf: <ContentTypes>(message: DecodedMessage<ContentTypes>, client: Client<ContentTypes>) => boolean;
+    hasContent: <ContentTypes>(message: DecodedMessage<ContentTypes>) => message is DecodedMessageWithContent<ContentTypes>;
+    isDM: (conversation: Conversation) => conversation is Dm;
+    isGroup: (conversation: Conversation) => conversation is Group;
+    isGroupAdmin: (conversation: Conversation, message: DecodedMessage) => boolean;
+    isGroupSuperAdmin: (conversation: Conversation, message: DecodedMessage) => boolean;
+    isGroupUpdate: (message: DecodedMessage) => message is DecodedMessageWithContent<GroupUpdated>;
+    isMarkdown: (message: DecodedMessage) => message is DecodedMessageWithContent<string>;
+    isReaction: (message: DecodedMessage) => message is DecodedMessageWithContent<Reaction>;
+    isReadReceipt: (message: DecodedMessage) => message is DecodedMessageWithContent<ReadReceipt>;
+    isRemoteAttachment: (message: DecodedMessage) => message is DecodedMessageWithContent<RemoteAttachment>;
+    isReply: (message: DecodedMessage) => message is DecodedMessageWithContent<EnrichedReply>;
+    isText: (message: DecodedMessage) => message is DecodedMessageWithContent<string>;
+    isTextReply: (message: DecodedMessage) => message is DecodedMessageWithContent<EnrichedReply<string>>;
+    isTransactionReference: (message: DecodedMessage) => message is DecodedMessageWithContent<TransactionReference>;
+    isWalletSendCalls: (message: DecodedMessage) => message is DecodedMessageWithContent<WalletSendCalls>;
+    usesCodec: <T extends ContentCodec>(message: DecodedMessage, codecClass: new () => T) => message is DecodedMessageWithContent<ReturnType<T["decode"]>>;
+};
+declare const f: {
+    fromSelf: <ContentTypes>(message: DecodedMessage<ContentTypes>, client: Client<ContentTypes>) => boolean;
+    hasContent: <ContentTypes>(message: DecodedMessage<ContentTypes>) => message is DecodedMessageWithContent<ContentTypes>;
+    isDM: (conversation: Conversation) => conversation is Dm;
+    isGroup: (conversation: Conversation) => conversation is Group;
+    isGroupAdmin: (conversation: Conversation, message: DecodedMessage) => boolean;
+    isGroupSuperAdmin: (conversation: Conversation, message: DecodedMessage) => boolean;
+    isGroupUpdate: (message: DecodedMessage) => message is DecodedMessageWithContent<GroupUpdated>;
+    isMarkdown: (message: DecodedMessage) => message is DecodedMessageWithContent<string>;
+    isReaction: (message: DecodedMessage) => message is DecodedMessageWithContent<Reaction>;
+    isReadReceipt: (message: DecodedMessage) => message is DecodedMessageWithContent<ReadReceipt>;
+    isRemoteAttachment: (message: DecodedMessage) => message is DecodedMessageWithContent<RemoteAttachment>;
+    isReply: (message: DecodedMessage) => message is DecodedMessageWithContent<EnrichedReply>;
+    isText: (message: DecodedMessage) => message is DecodedMessageWithContent<string>;
+    isTextReply: (message: DecodedMessage) => message is DecodedMessageWithContent<EnrichedReply<string>>;
+    isTransactionReference: (message: DecodedMessage) => message is DecodedMessageWithContent<TransactionReference>;
+    isWalletSendCalls: (message: DecodedMessage) => message is DecodedMessageWithContent<WalletSendCalls>;
+    usesCodec: <T extends ContentCodec>(message: DecodedMessage, codecClass: new () => T) => message is DecodedMessageWithContent<ReturnType<T["decode"]>>;
+};
+
+type MessageContextParams<MessageContentType = unknown, ContentTypes = unknown> = Omit<AgentBaseContext<ContentTypes>, "message"> & {
+    message: DecodedMessageWithContent<MessageContentType>;
+};
+declare class MessageContext<MessageContentType = unknown, ContentTypes = unknown> extends ConversationContext<ContentTypes> {
+    #private;
+    constructor({ message, conversation, client, }: MessageContextParams<MessageContentType, ContentTypes>);
+    usesCodec<T extends ContentCodec>(codecClass: new () => T): this is MessageContext<ReturnType<T["decode"]>>;
+    isMarkdown(): this is MessageContext<string>;
+    isText(): this is MessageContext<string>;
+    isReply(): this is MessageContext<Reply>;
+    isReaction(): this is MessageContext<Reaction>;
+    isReadReceipt(): this is MessageContext<ReadReceipt>;
+    isRemoteAttachment(): this is MessageContext<RemoteAttachment>;
+    isTransactionReference(): this is MessageContext<TransactionReference>;
+    isWalletSendCalls(): this is MessageContext<WalletSendCalls>;
+    sendReaction(content: string, schema?: Reaction["schema"]): Promise<void>;
+    sendMarkdownReply(markdown: string): Promise<void>;
+    sendTextReply(text: string): Promise<void>;
+    getSenderAddress(): Promise<string | undefined>;
+    get message(): DecodedMessageWithContent<MessageContentType>;
+}
+
+type EventHandlerMap<ContentTypes> = {
+    attachment: [ctx: MessageContext<RemoteAttachment, ContentTypes>];
+    conversation: [ctx: ConversationContext<ContentTypes>];
+    "group-update": [ctx: MessageContext<GroupUpdated, ContentTypes>];
+    dm: [ctx: ConversationContext<ContentTypes, Dm<ContentTypes>>];
+    group: [ctx: ConversationContext<ContentTypes, Group<ContentTypes>>];
+    markdown: [ctx: MessageContext<string, ContentTypes>];
+    message: [ctx: MessageContext<unknown, ContentTypes>];
+    reaction: [ctx: MessageContext<Reaction, ContentTypes>];
+    "read-receipt": [ctx: MessageContext<ReadReceipt, ContentTypes>];
+    reply: [ctx: MessageContext<Reply, ContentTypes>];
+    start: [ctx: ClientContext<ContentTypes>];
+    stop: [ctx: ClientContext<ContentTypes>];
+    text: [ctx: MessageContext<string, ContentTypes>];
+    "transaction-reference": [
+        ctx: MessageContext<TransactionReference, ContentTypes>
+    ];
+    unhandledError: [error: Error];
+    unknownMessage: [ctx: MessageContext<unknown, ContentTypes>];
+    "wallet-send-calls": [ctx: MessageContext<WalletSendCalls, ContentTypes>];
+};
+type EthAddress = HexString;
+type AgentBaseContext<ContentTypes = unknown> = {
+    client: Client<ContentTypes>;
+    conversation: Conversation;
+    message: DecodedMessage;
+};
+type AgentErrorContext<ContentTypes = unknown> = Partial<AgentBaseContext<ContentTypes>> & {
+    client: Client<ContentTypes>;
+};
+type AgentOptions<ContentTypes> = {
+    client: Client<ContentTypes>;
+};
+type AgentMessageHandler<ContentTypes = unknown> = (ctx: MessageContext<ContentTypes>) => Promise<void> | void;
+type AgentMiddleware<ContentTypes = unknown> = (ctx: MessageContext<unknown, ContentTypes>, next: () => Promise<void> | void) => Promise<void>;
+type AgentErrorMiddleware<ContentTypes = unknown> = (error: unknown, ctx: AgentErrorContext<ContentTypes>, next: (err?: unknown) => Promise<void> | void) => Promise<void> | void;
+type AgentStreamingOptions = Omit<StreamOptions, "onValue" | "onError">;
+type StreamAllMessagesOptions<ContentTypes> = Parameters<Client<ContentTypes>["conversations"]["streamAllMessages"]>[0];
+type AgentErrorRegistrar<ContentTypes> = {
+    use(...errorMiddleware: Array<AgentErrorMiddleware<ContentTypes> | AgentErrorMiddleware<ContentTypes>[]>): AgentErrorRegistrar<ContentTypes>;
+};
+declare class Agent<ContentTypes = unknown> extends EventEmitter<EventHandlerMap<ContentTypes>> {
+    #private;
+    constructor({ client }: AgentOptions<ContentTypes>);
+    static create<ContentCodecs extends ContentCodec[] = []>(signer: Parameters<typeof Client.create>[0], options?: Omit<ClientOptions, "codecs"> & {
+        codecs?: ContentCodecs;
+    }): Promise<Agent<_xmtp_node_sdk.ExtractCodecContentTypes<ContentCodecs>>>;
+    static createFromEnv<ContentCodecs extends ContentCodec[] = []>(options?: Omit<ClientOptions, "codecs"> & {
+        codecs?: ContentCodecs;
+    }): Promise<Agent<_xmtp_node_sdk.ExtractCodecContentTypes<ContentCodecs>>>;
+    get libxmtpVersion(): string | undefined;
+    use(...middleware: Array<AgentMiddleware<ContentTypes> | AgentMiddleware<ContentTypes>[]>): this;
+    start(options?: AgentStreamingOptions): Promise<void>;
+    get client(): Client<ContentTypes>;
+    get errors(): AgentErrorRegistrar<ContentTypes>;
+    stop(): Promise<void>;
+    createDmWithAddress(address: EthAddress, options?: CreateDmOptions): Promise<Dm<ContentTypes>>;
+    createGroupWithAddresses(addresses: EthAddress[], options?: CreateGroupOptions): Promise<Group<ContentTypes>>;
+    addMembersWithAddresses<ContentTypes>(group: Group<ContentTypes>, addresses: EthAddress[]): Promise<void>;
+    getConversationContext(conversationId: string): Promise<ConversationContext<ContentTypes, Dm<ContentTypes> | Group<ContentTypes>> | undefined>;
+    get address(): string | undefined;
+}
+
+declare class AgentError extends Error {
+    #private;
+    constructor(code: number, message: string, cause?: unknown);
+    get code(): number;
+}
+declare class AgentStreamingError extends AgentError {
+}
+
+declare const logDetails: <ContentTypes>(agent: Agent<ContentTypes>) => Promise<void>;
+/**
+ * Returns a URL to test your agent on https://xmtp.chat/ (for development purposes only).
+ *
+ * @param client - Your XMTP client
+ * @returns The URL to test your agent with
+ */
+declare const getTestUrl: <ContentTypes>(client: Client<ContentTypes>) => string;
+type InstallationInfo = {
+    totalInstallations: number;
+    installationId: string;
+    mostRecentInstallationId: null | string;
+    isMostRecent: boolean;
+};
+declare const getInstallationInfo: <ContentTypes>(client: Client<ContentTypes>) => Promise<InstallationInfo>;
+
+/** Content type supported by the "CommandRouter" */
+type SupportedType = string;
+declare class CommandRouter<ContentTypes = BuiltInContentTypes> {
+    #private;
+    get commandList(): string[];
+    command(command: string, handler: AgentMessageHandler<SupportedType>): this;
+    default(handler: AgentMessageHandler<SupportedType>): this;
+    handle(ctx: MessageContext<SupportedType>): Promise<boolean>;
+    middleware(): AgentMiddleware<ContentTypes>;
+}
+
+type User = {
+    key: Hex;
+    account: PrivateKeyAccount;
+    wallet: WalletClient;
+};
+declare const createUser: (key?: HexString, chain?: Chain) => User;
+declare const createIdentifier: (user: User) => Identifier;
+declare const createSigner: (user: User) => Signer;
+
+declare const createNameResolver: (apiKey?: string) => (name: string) => Promise<string | null>;
+
+export { Agent, AgentError, AgentStreamingError, ClientContext, CommandRouter, ConversationContext, MessageContext, createIdentifier, createNameResolver, createRemoteAttachment, createRemoteAttachmentFromFile, createSigner, createUser, downloadRemoteAttachment, f, filter, getInstallationInfo, getTestUrl, logDetails };
+export type { AgentBaseContext, AgentErrorContext, AgentErrorMiddleware, AgentErrorRegistrar, AgentMessageHandler, AgentMiddleware, AgentOptions, AgentStreamingOptions, AttachmentUploadCallback, DecodedMessageWithContent, MessageContextParams, StreamAllMessagesOptions, User };