@xmtp/agent-sdk 0.0.3 → 0.0.4

package/README.md

@@ -1,27 +1,83 @@
-# XMTP Agent SDK for Node
+# XMTP Agent SDK
 
-This package provides the XMTP Agent SDK for Node.
-
-To keep up with the latest SDK developments, see the [Issues tab](https://github.com/xmtp/xmtp-js/issues) in this repo.
+Build event‑driven, middleware‑powered messaging agents on the XMTP network. 🚀
 
 > [!CAUTION]
 > This SDK is in beta status and ready for you to build with in production. Software in this status may change based on feedback.
 
-## Features
+## Documentation
+
+Full agent building guide: **[Build an XMTP Agent](https://docs.xmtp.org/agents/get-started/build-an-agent)**
 
-### Event-driven architecture
+This SDK is based on familiar Node.js patterns: you register event listeners, compose middleware, and extend behavior just like you would in frameworks such as [Express](https://expressjs.com/). This makes it easy to bring existing JavaScript and TypeScript skills into building conversational agents.
 
-Subscribe to specific events and receive only the ones that matter to you using Node's `EventEmitter`:
+## Installation
+
+Choose your package manager:
+
+```bash
+npm install @xmtp/agent-sdk @xmtp/node-sdk
+# or
+pnpm add @xmtp/agent-sdk @xmtp/node-sdk
+# or
+yarn add @xmtp/agent-sdk @xmtp/node-sdk
+```
+
+## Quick Start
 
 ```ts
+import { Agent, createSigner, createUser } from "@xmtp/agent-sdk";
+
+// 1. Create a local user + signer (you can plug in your own wallet signer)
+const user = createUser();
+const signer = createSigner(user);
+
+// 2. Spin up the agent
+const agent = await Agent.create(signer, {
+  env: "dev", // or 'production'
+  dbPath: null, // in-memory store; provide a path to persist
+});
+
+// 3. Respond to any incoming message
 agent.on("message", async (ctx) => {
-  await ctx.conversation.send("Hello!");
+  await ctx.conversation.send("Hello from my XMTP Agent! 👋");
+});
+
+// 4. Log when we're ready
+agent.on("start", () => {
+  const address = agent.client.accountIdentifier?.identifier;
+  const env = agent.client.options?.env;
+  console.log(`Agent online: http://xmtp.chat/dm/${address}?env=${env}`);
+});
+
+await agent.start();
+```
+
+## Core Concepts
+
+### 1. Event‑Driven Architecture
+
+Subscribe only to what you need using Node’s `EventEmitter` interface.
+
+Events you can listen for:
+
+- `message` – a new incoming (non‑self) message
+- `start` / `stop` – lifecycle events
+- `error` – surfaced errors
+
+**Example:**
+
+```ts
+agent.on("error", (error) => {
+  console.error("Agent error", error);
 });
 ```
 
-### Middleware support
+### 2. Middleware Support
 
-Build flexible middleware pipelines by composing the tools you need (Custom Filters, Telemetry, Analytics, …):
+Extend your agent with custom business logic using middlewares. Compose cross-cutting behavior like routing, telemetry, rate limiting, analytics, and feature flags, or plug in your own.
+
+**Example:**
 
 ```ts
 const router = new CommandRouter();
@@ -30,19 +86,79 @@ router.command("/start", async (ctx) => {
   await ctx.conversation.send("👋 Welcome to your XMTP agent!");
 });
 
-const agent = new Agent({ client });
 agent.use(router.middleware());
 ```
 
-### Built-in Filters
+### 3. Built‑in Filters
+
+Instead of manually checking every incoming message, you can compose simple, reusable filters that make intent clear.
 
-Skip repetitive condition checks with ready-to-use message filters, easily chained through a fluent API:
+**Example:**
 
 ```ts
+import { withFilter, filter } from "@xmtp/agent-sdk";
+
+const filters = filter.and(filter.notFromSelf, filter.textOnly);
+
 agent.on(
   "message",
-  withFilter(filter.and(filter.notFromSelf, filter.textOnly), async (ctx) => {
-    await ctx.conversation.send("Hey!");
+  withFilter(filters, async (ctx) => {
+    await ctx.conversation.send("You sent a text message ✅");
   }),
 );
 ```
+
+### 4. Rich Context
+
+Every `message` handler receives an `AgentContext` with:
+
+- `message` – decoded message
+- `conversation` – the active conversation object
+- `client` – underlying XMTP client
+- Helpers like `sendText()` / `sendTextReply()`
+
+**Example:**
+
+```ts
+agent.on("message", async (ctx) => {
+  await ctx.sendTextReply("Reply using helper ✨");
+});
+```
+
+## Adding Custom Content Types
+
+Pass codecs when creating your agent to extend supported content:
+
+```ts
+import { ReplyCodec } from "@xmtp/content-type-reply";
+
+const agent = await Agent.create(signer, {
+  env: "dev",
+  dbPath: null,
+  codecs: [new ReplyCodec()],
+});
+```
+
+## Development Resources
+
+- [Debug an agent](https://docs.xmtp.org/agents/debug-agents)
+- [Further debugging info](https://docs.xmtp.org/inboxes/debug-your-app#debug-your-inbox-app)
+
+## FAQ (Quick Hits)
+
+| Question                                                                                     | Answer                                          |
+| -------------------------------------------------------------------------------------------- | ----------------------------------------------- |
+| Does middleware run for every message?                                                       | Yes, in the order added.                        |
+| How do I reject a message early?                                                             | Don’t call `next()` in middleware.              |
+| How do I filter messages?                                                                    | Use `withFilter(...)` around an event listener. |
+| Can I send custom [content types](https://docs.xmtp.org/agents/content-types/content-types)? | Yes, register codecs during agent creation.     |
+
+## Contributing / Feedback
+
+We’d love your feedback: [open an issue](https://github.com/xmtp/xmtp-js/issues) or discussion. PRs welcome for docs, examples, and core improvements.
+
+---
+
+Build something delightful. Then tell us what you wish was easier.
+
+Happy hacking 💫

package/dist/core/Agent.js

@@ -1,6 +1,6 @@
 import EventEmitter from "node:events";
 import { Client, } from "@xmtp/node-sdk";
-import { filter } from "@/utils/filter.js";
+import { filter } from "../utils/filter.js";
 import { AgentContext } from "./AgentContext.js";
 export class Agent extends EventEmitter {
     #client;

package/dist/utils/filter.d.ts

@@ -1,5 +1,5 @@
 import type { Client, DecodedMessage } from "@xmtp/node-sdk";
-import type { AgentContext } from "@/core/AgentContext.js";
+import type { AgentContext } from "../core/AgentContext.js";
 /**
  * Function type for filtering messages based on content and client state.
  */

package/package.json

@@ -13,6 +13,7 @@
     "@arethetypeswrong/cli": "^0.18.2",
     "@types/node": "^22.16.3",
     "@vitest/coverage-v8": "^3.2.4",
+    "tsc-alias": "^1.8.16",
     "tsx": "^4.20.3",
     "typescript": "^5.8.3",
     "vite": "^7.0.4",
@@ -53,7 +54,7 @@
     "url": "git+https://git@github.com/xmtp/xmtp-js.git"
   },
   "scripts": {
-    "build": "yarn clean:dist && tsc -p tsconfig.build.json && attw --pack . --ignore-rules cjs-resolves-to-esm",
+    "build": "yarn clean:dist && tsc -p tsconfig.build.json && tsc-alias && attw --pack . --ignore-rules cjs-resolves-to-esm",
     "clean": "rm -rf .turbo && rm -rf node_modules && yarn clean:dist",
     "clean:dist": "rm -rf dist",
     "dev": "tsx --watch src/main.ts",
@@ -63,5 +64,5 @@
     "typecheck": "tsc --noEmit"
   },
   "type": "module",
-  "version": "0.0.3"
+  "version": "0.0.4"
 }