@xmtp/agent-sdk 0.0.3 → 0.0.5

package/README.md

@@ -1,48 +1,212 @@
-# 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)**
+
+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.
+
+## Installation
+
+Choose your package manager:
 
-### Event-driven architecture
+```bash
+npm install @xmtp/agent-sdk
+# or
+pnpm add @xmtp/agent-sdk
+# or
+yarn add @xmtp/agent-sdk
+```
 
-Subscribe to specific events and receive only the ones that matter to you using Node's `EventEmitter`:
+## 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();
 ```
 
-### Middleware support
+## Environment Variables
+
+The XMTP Agent SDK supports environment variables (`process.env`) to simplify configuration without code changes.
+
+**Available Variables:**
 
-Build flexible middleware pipelines by composing the tools you need (Custom Filters, Telemetry, Analytics, …):
+| Variable                          | Purpose                                                                                                                      | Example                                 |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| `XMTP_WALLET_KEY`                 | [Private key for wallet](https://docs.xmtp.org/inboxes/core-messaging/create-a-signer)                                       | `XMTP_WALLET_KEY=0x1234...abcd`         |
+| `XMTP_ENV`                        | [Network environment](https://docs.xmtp.org/agents/core-messaging/create-a-client#xmtp-network-environments)                 | `XMTP_ENV=dev` or `XMTP_ENV=production` |
+| `XMTP_DB_ENCRYPTION_KEY`          | [Database encryption key](https://docs.xmtp.org/agents/core-messaging/create-a-client#keep-the-database-encryption-key-safe) | `XMTP_DB_ENCRYPTION_KEY=0xabcd...1234`  |
+| `XMTP_FORCE_DEBUG`                | [Activate debugging logs](https://docs.xmtp.org/agents/debug-agents)                                                         | `XMTP_FORCE_DEBUG=true`                 |
+| `XMTP_FORCE_REVOKE_INSTALLATIONS` | [Remove other installations](https://docs.xmtp.org/agents/core-messaging/agent-installations#revoke-agent-installations)     | `XMTP_FORCE_REVOKE_INSTALLATIONS=true`  |
+
+Using the environment variables, you can setup your agent in just a few lines of code:
 
 ```ts
+// Load variables from .env file
+process.loadEnvFile(".env");
+
+// Create agent using environment variables
+const agent = await Agent.create();
+```
+
+## 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);
+});
+```
+
+### 2. Middleware Support
+
+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
+import { CommandRouter } from "@xmtp/agent-sdk";
+
 const router = new CommandRouter();
 
-router.command("/start", async (ctx) => {
-  await ctx.conversation.send("👋 Welcome to your XMTP agent!");
+router.command("/version", async (ctx) => {
+  await ctx.conversation.send(`v${process.env.npm_package_version}`);
 });
 
-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";
+
+// Using filter in message handler
 agent.on(
   "message",
-  withFilter(filter.and(filter.notFromSelf, filter.textOnly), async (ctx) => {
-    await ctx.conversation.send("Hey!");
+  withFilter(filter.startsWith("@agent"), async (ctx) => {
+    await ctx.conversation.send("How can I help you?");
   }),
 );
+
+// Combination of filters
+const combined = filter.and(filter.notFromSelf, filter.textOnly);
+
+agent.on(
+  "message",
+  withFilter(combined, async (ctx) => {
+    await ctx.conversation.send("You sent a text message ✅");
+  }),
+);
+```
+
+For convenience, the `filter` object can also be imported as `f`:
+
+```ts
+// You can import either name:
+import { filter, f } from "@xmtp/agent-sdk";
+
+// Both work the same way:
+const longVersion = filter.and(filter.notFromSelf, filter.textOnly);
+const shortVersion = f.and(f.notFromSelf, f.textOnly);
+```
+
+You can find all available prebuilt filters [here](https://github.com/xmtp/xmtp-js/blob/main/sdks/agent-sdk/src/utils/filter.ts).
+
+### 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()],
+});
 ```
+
+## Debugging
+
+- [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/bin/generateKeys.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/generateKeys.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { generateClientKeys } from "../utils/crypto.js";
+/**
+ * Generates client keys and saves them to a .env file in the project root.
+ * This script creates the necessary environment variables for XMTP agent initialization.
+ */
+function main() {
+    try {
+        // Generate the client keys
+        const keys = generateClientKeys();
+        // Create the .env file content
+        const envContent = Object.entries(keys)
+            .map(([key, value]) => `${key}=${value}`)
+            .join("\n") + "\n";
+        if (!process.env.INIT_CWD) {
+            throw new Error(`Cannot invoke script because "process.env.INIT_CWD" wasn't found.`);
+        }
+        const envFilePath = join(process.env.INIT_CWD, ".env");
+        writeFileSync(envFilePath, envContent, "utf8");
+        console.log("✅ Successfully generated client keys and saved to .env file");
+        console.log(`📁 File location: ${envFilePath}`);
+        console.log("🔑 Generated keys:");
+        Object.keys(keys).forEach((key) => {
+            console.log(`   - ${key}`);
+        });
+    }
+    catch (error) {
+        console.error("❌ Error generating client keys:", error);
+        process.exit(1);
+    }
+}
+main();
+//# sourceMappingURL=generateKeys.js.map

package/dist/bin/generateKeys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateKeys.js","sourceRoot":"","sources":["../../src/bin/generateKeys.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD;;;GAGG;AACH,SAAS,IAAI;IACX,IAAI,CAAC;QACH,2BAA2B;QAC3B,MAAM,IAAI,GAAG,kBAAkB,EAAE,CAAC;QAElC,+BAA+B;QAC/B,MAAM,UAAU,GACd,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC;aACjB,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,IAAI,KAAK,EAAE,CAAC;aACxC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;QAEvB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CACb,mEAAmE,CACpE,CAAC;QACJ,CAAC;QACD,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAEvD,aAAa,CAAC,WAAW,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;QAE/C,OAAO,CAAC,GAAG,CAAC,6DAA6D,CAAC,CAAC;QAC3E,OAAO,CAAC,GAAG,CAAC,qBAAqB,WAAW,EAAE,CAAC,CAAC;QAChD,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;QAClC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE;YAChC,OAAO,CAAC,GAAG,CAAC,QAAQ,GAAG,EAAE,CAAC,CAAC;QAC7B,CAAC,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,iCAAiC,EAAE,KAAK,CAAC,CAAC;QACxD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC"}

package/dist/core/Agent.d.ts

@@ -1,5 +1,8 @@
 import EventEmitter from "node:events";
 import type { ContentCodec } from "@xmtp/content-type-primitives";
+import { ReactionCodec } from "@xmtp/content-type-reaction";
+import { RemoteAttachmentCodec } from "@xmtp/content-type-remote-attachment";
+import { ReplyCodec } from "@xmtp/content-type-reply";
 import { Client, type ClientOptions } from "@xmtp/node-sdk";
 import { AgentContext } from "./AgentContext.js";
 interface EventHandlerMap<ContentTypes> {
@@ -11,16 +14,14 @@ interface EventHandlerMap<ContentTypes> {
 export interface AgentOptions<ContentTypes> {
     client: Client<ContentTypes>;
 }
+export type AgentEventHandler<ContentTypes = unknown> = (ctx: AgentContext<ContentTypes>) => Promise<void> | void;
 export type AgentMiddleware<ContentTypes> = (ctx: AgentContext<ContentTypes>, next: () => Promise<void>) => Promise<void>;
 export declare class Agent<ContentTypes> extends EventEmitter<EventHandlerMap<ContentTypes>> {
     #private;
     constructor({ client }: AgentOptions<ContentTypes>);
-    static create<ContentCodecs extends ContentCodec[] = []>(signer: Parameters<typeof Client.create>[0], options?: Omit<ClientOptions, "codecs"> & {
+    static create<ContentCodecs extends ContentCodec[] = []>(signer?: Parameters<typeof Client.create>[0], options?: Omit<ClientOptions, "codecs"> & {
         codecs?: ContentCodecs;
-    }): Promise<Agent<import("@xmtp/node-sdk").ExtractCodecContentTypes<ContentCodecs>>>;
-    static build<ContentCodecs extends ContentCodec[] = []>(identifier: Parameters<typeof Client.build>[0], options?: Omit<ClientOptions, "codecs"> & {
-        codecs?: ContentCodecs;
-    }): Promise<Agent<import("@xmtp/node-sdk").ExtractCodecContentTypes<ContentCodecs>>>;
+    }): Promise<Agent<import("@xmtp/node-sdk").ExtractCodecContentTypes<(ReactionCodec | ReplyCodec | RemoteAttachmentCodec | (never[] | ContentCodecs)[number])[]>>>;
     use(middleware: AgentMiddleware<ContentTypes>): this;
     start(): Promise<void>;
     get client(): Client<ContentTypes>;

package/dist/core/Agent.js

@@ -1,6 +1,13 @@
 import EventEmitter from "node:events";
-import { Client, } from "@xmtp/node-sdk";
-import { filter } from "@/utils/filter.js";
+import { ReactionCodec } from "@xmtp/content-type-reaction";
+import { RemoteAttachmentCodec } from "@xmtp/content-type-remote-attachment";
+import { ReplyCodec } from "@xmtp/content-type-reply";
+import { ApiUrls, Client, } from "@xmtp/node-sdk";
+import { isHex } from "viem/utils";
+import { getEncryptionKeyFromHex } from "../utils/crypto.js";
+import { logDetails } from "../utils/debug.js";
+import { filter } from "../utils/filter.js";
+import { createSigner, createUser } from "../utils/user.js";
 import { AgentContext } from "./AgentContext.js";
 export class Agent extends EventEmitter {
     #client;
@@ -13,13 +20,44 @@ export class Agent extends EventEmitter {
     static async create(signer, 
     // Note: we need to omit this so that "Client.create" can correctly infer the codecs.
     options) {
-        const client = await Client.create(signer, options);
-        return new Agent({ client });
-    }
-    static async build(identifier, 
-    // Note: we need to omit this so that "Client.build" can correctly infer the codecs.
-    options) {
-        const client = await Client.build(identifier, options);
+        if (!signer) {
+            if (isHex(process.env.XMTP_WALLET_KEY)) {
+                signer = createSigner(createUser(process.env.XMTP_WALLET_KEY));
+            }
+            else {
+                throw new Error(`No signer detected. Provide a "signer" to "Agent.create()" or set the "XMTP_WALLET_KEY" environment variable to a private key in hexadecimal format. Read more: https://docs.xmtp.org/inboxes/core-messaging/create-a-signer`);
+            }
+        }
+        const initializedOptions = { ...options };
+        initializedOptions.appVersion ??= "agent-sdk/alpha";
+        if (process.env.XMTP_DB_ENCRYPTION_KEY) {
+            initializedOptions.dbEncryptionKey = getEncryptionKeyFromHex(process.env.XMTP_DB_ENCRYPTION_KEY);
+        }
+        if (process.env.XMTP_ENV &&
+            Object.keys(ApiUrls).includes(process.env.XMTP_ENV)) {
+            initializedOptions.env = process.env.XMTP_ENV;
+        }
+        if (process.env.XMTP_FORCE_DEBUG) {
+            initializedOptions.debugEventsEnabled = true;
+            initializedOptions.loggingLevel = "warn" /* LogLevel.warn */;
+            initializedOptions.structuredLogging = true;
+        }
+        const upgradedCodecs = [
+            ...(initializedOptions.codecs ?? []),
+            new ReactionCodec(),
+            new ReplyCodec(),
+            new RemoteAttachmentCodec(),
+        ];
+        const client = await Client.create(signer, {
+            ...initializedOptions,
+            codecs: upgradedCodecs,
+        });
+        if (process.env.XMTP_FORCE_REVOKE_INSTALLATIONS) {
+            await client.revokeAllOtherInstallations();
+        }
+        if (process.env.XMTP_FORCE_DEBUG) {
+            await logDetails(client);
+        }
         return new Agent({ client });
     }
     use(middleware) {

package/dist/core/Agent.js.map

@@ -1 +1 @@
-{"version":3,"file":"Agent.js","sourceRoot":"","sources":["../../src/core/Agent.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,aAAa,CAAC;AAEvC,OAAO,EACL,MAAM,GAGP,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAkBjD,MAAM,OAAO,KAAoB,SAAQ,YAExC;IACC,OAAO,CAAuB;IAC9B,WAAW,GAAoC,EAAE,CAAC;IAClD,YAAY,GAAG,KAAK,CAAC;IAErB,YAAY,EAAE,MAAM,EAA8B;QAChD,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IAED,MAAM,CAAC,KAAK,CAAC,MAAM,CACjB,MAA2C;IAC3C,qFAAqF;IACrF,OAAoE;QAEpE,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpD,OAAO,IAAI,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;IAC/B,CAAC;IAED,MAAM,CAAC,KAAK,CAAC,KAAK,CAChB,UAA8C;IAC9C,oFAAoF;IACpF,OAAoE;QAEpE,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QACvD,OAAO,IAAI,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;IAC/B,CAAC;IAED,GAAG,CAAC,UAAyC;QAC3C,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAClC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,OAAO;QACT,CAAC;QAED,IAAI,CAAC;YACH,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;YACzB,KAAK,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAExB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,iBAAiB,EAAE,CAAC;YACpE,IAAI,KAAK,EAAE,MAAM,OAAO,IAAI,MAAM,EAAE,CAAC;gBACnC,yCAAyC;gBACzC,uEAAuE;gBACvE,IAAI,CAAC,IAAI,CAAC,YAAY;oBAAE,MAAM;gBAC9B,IAAI,CAAC;oBACH,MAAM,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;gBACtC,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;gBAC1B,CAAC;YACH,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC;YAC1B,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IAED,KAAK,CAAC,eAAe,CAAC,OAAqC;QACzD,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,mBAAmB,CACvE,OAAO,CAAC,cAAc,CACvB,CAAC;QAEF,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,IAAI,CAAC,WAAW,CACd,IAAI,KAAK,CACP,iCAAiC,OAAO,CAAC,EAAE,0BAA0B,OAAO,CAAC,cAAc,gDAAgD,CAC5I,CACF,CAAC;YACF,OAAO;QACT,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,OAAO,EAAE,YAAY,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAEtE,IAAI,eAAe,GAAG,CAAC,CAAC;QACxB,MAAM,IAAI,GAAG,KAAK,IAAI,EAAE;YACtB,IAAI,eAAe,GAAG,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC;gBAC9C,MAAM,iBAAiB,GAAG,IAAI,CAAC,WAAW,CAAC,eAAe,EAAE,CAAC,CAAC;gBAC9D,MAAM,iBAAiB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;YACzC,CAAC;iBAAM,IAAI,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;gBACrD,0DAA0D;gBAC1D,2DAA2D;gBAC3D,KAAK,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;YACrC,CAAC;QACH,CAAC,CAAC;QAEF,MAAM,IAAI,EAAE,CAAC;IACf,CAAC;IAED,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,IAAI;QACF,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC;QAC1B,KAAK,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACzB,CAAC;IAED,WAAW,CAAC,KAAc;QACxB,MAAM,QAAQ,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAC3E,KAAK,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACpC,CAAC;CACF"}
+{"version":3,"file":"Agent.js","sourceRoot":"","sources":["../../src/core/Agent.ts"],"names":[],"mappings":"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"}

package/dist/core/AgentContext.d.ts

@@ -1,9 +1,12 @@
+import { type Reaction } from "@xmtp/content-type-reaction";
 import type { Client, Conversation, DecodedMessage } from "@xmtp/node-sdk";
 export declare class AgentContext<ContentTypes = unknown> {
     #private;
     constructor(message: DecodedMessage<ContentTypes>, conversation: Conversation, client: Client<ContentTypes>);
+    sendReaction(content: string, schema: Reaction["schema"]): Promise<void>;
     sendText(text: string): Promise<void>;
     sendTextReply(text: string): Promise<void>;
+    getOwnAddress(): string | undefined;
     getSenderAddress(): Promise<string>;
     get message(): DecodedMessage<ContentTypes>;
     get conversation(): Conversation<unknown>;

package/dist/core/AgentContext.js

@@ -1,3 +1,4 @@
+import { ContentTypeReaction, } from "@xmtp/content-type-reaction";
 import { ContentTypeReply } from "@xmtp/content-type-reply";
 import { ContentTypeText } from "@xmtp/content-type-text";
 export class AgentContext {
@@ -9,6 +10,16 @@ export class AgentContext {
         this.#conversation = conversation;
         this.#client = client;
     }
+    async sendReaction(content, schema) {
+        const reaction = {
+            action: "added",
+            reference: this.#message.id,
+            referenceInboxId: this.#message.senderInboxId,
+            schema,
+            content,
+        };
+        await this.#conversation.send(reaction, ContentTypeReaction);
+    }
     async sendText(text) {
         await this.#conversation.send(text, ContentTypeText);
     }
@@ -21,6 +32,9 @@ export class AgentContext {
         };
         await this.#conversation.send(reply, ContentTypeReply);
     }
+    getOwnAddress() {
+        return this.#client.accountIdentifier?.identifier;
+    }
     async getSenderAddress() {
         const inboxState = await this.#client.preferences.inboxStateFromInboxIds([
             this.#message.senderInboxId,

package/dist/core/AgentContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"AgentContext.js","sourceRoot":"","sources":["../../src/core/AgentContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAc,MAAM,0BAA0B,CAAC;AACxE,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAG1D,MAAM,OAAO,YAAY;IACvB,OAAO,CAAuB;IAC9B,QAAQ,CAA+B;IACvC,aAAa,CAAe;IAE5B,YACE,OAAqC,EACrC,YAA0B,EAC1B,MAA4B;QAE5B,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACxB,IAAI,CAAC,aAAa,GAAG,YAAY,CAAC;QAClC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,IAAY;QACzB,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;IACvD,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,IAAY;QAC9B,MAAM,KAAK,GAAU;YACnB,SAAS,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE;YAC3B,gBAAgB,EAAE,IAAI,CAAC,QAAQ,CAAC,aAAa;YAC7C,WAAW,EAAE,eAAe;YAC5B,OAAO,EAAE,IAAI;SACd,CAAC;QACF,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,EAAE,gBAAgB,CAAC,CAAC;IACzD,CAAC;IAED,KAAK,CAAC,gBAAgB;QACpB,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,sBAAsB,CAAC;YACvE,IAAI,CAAC,QAAQ,CAAC,aAAa;SAC5B,CAAC,CAAC;QACH,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;IACjD,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,IAAI,YAAY;QACd,OAAO,IAAI,CAAC,aAAa,CAAC;IAC5B,CAAC;IAED,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;CACF"}
+{"version":3,"file":"AgentContext.js","sourceRoot":"","sources":["../../src/core/AgentContext.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,GAEpB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,gBAAgB,EAAc,MAAM,0BAA0B,CAAC;AACxE,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAG1D,MAAM,OAAO,YAAY;IACvB,OAAO,CAAuB;IAC9B,QAAQ,CAA+B;IACvC,aAAa,CAAe;IAE5B,YACE,OAAqC,EACrC,YAA0B,EAC1B,MAA4B;QAE5B,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACxB,IAAI,CAAC,aAAa,GAAG,YAAY,CAAC;QAClC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,OAAe,EAAE,MAA0B;QAC5D,MAAM,QAAQ,GAAa;YACzB,MAAM,EAAE,OAAO;YACf,SAAS,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE;YAC3B,gBAAgB,EAAE,IAAI,CAAC,QAAQ,CAAC,aAAa;YAC7C,MAAM;YACN,OAAO;SACR,CAAC;QACF,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,QAAQ,EAAE,mBAAmB,CAAC,CAAC;IAC/D,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,IAAY;QACzB,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;IACvD,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,IAAY;QAC9B,MAAM,KAAK,GAAU;YACnB,SAAS,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE;YAC3B,gBAAgB,EAAE,IAAI,CAAC,QAAQ,CAAC,aAAa;YAC7C,WAAW,EAAE,eAAe;YAC5B,OAAO,EAAE,IAAI;SACd,CAAC;QACF,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,EAAE,gBAAgB,CAAC,CAAC;IACzD,CAAC;IAED,aAAa;QACX,OAAO,IAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE,UAAU,CAAC;IACpD,CAAC;IAED,KAAK,CAAC,gBAAgB;QACpB,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,sBAAsB,CAAC;YACvE,IAAI,CAAC,QAAQ,CAAC,aAAa;SAC5B,CAAC,CAAC;QACH,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;IACjD,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,IAAI,YAAY;QACd,OAAO,IAAI,CAAC,aAAa,CAAC;IAC5B,CAAC;IAED,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;CACF"}

package/dist/demo.js

@@ -1,33 +1,36 @@
-import { ReplyCodec } from "@xmtp/content-type-reply";
+import { loadEnvFile } from "node:process";
 import { Agent } from "./core/index.js";
-import { createSigner, createUser, filter as f, withFilter, } from "./utils/index.js";
-const user = createUser();
-const signer = createSigner(user);
-const agent = await Agent.create(signer, {
-    codecs: [new ReplyCodec()],
-    dbPath: null,
-    env: "dev",
+import { CommandRouter } from "./middleware/CommandRouter.js";
+import { getTestUrl } from "./utils/debug.js";
+import { createSigner, createUser, f, withFilter } from "./utils/index.js";
+try {
+    loadEnvFile(".env");
+    console.info(`Loaded keys from ".env" file.`);
+}
+catch { }
+const agent = process.env.XMTP_WALLET_KEY
+    ? await Agent.create()
+    : await Agent.create(createSigner(createUser()), {
+        dbPath: null,
+    });
+const router = new CommandRouter();
+router.command("/version", async (ctx) => {
+    await ctx.conversation.send(`v${process.env.npm_package_version}`);
 });
-agent.on("message", (ctx) => {
-    void ctx.conversation.send("First message!");
-});
-agent.on("message", withFilter(f.and(f.notFromSelf, f.textOnly), (ctx) => {
-    void ctx.conversation.send("Goodbye!");
-    agent.stop();
-}));
+agent.use(router.middleware());
 agent.on("message", (ctx) => {
     console.log("Got message:", ctx.message.content);
 });
+agent.on("message", withFilter(f.startsWith("@agent"), async (ctx) => {
+    await ctx.conversation.send("How can I help you?");
+}));
 const errorHandler = (error) => {
     console.log("Caught error", error);
 };
 agent.on("error", errorHandler);
 agent.off("error", errorHandler);
 agent.on("start", () => {
-    const address = agent.client.accountIdentifier?.identifier;
-    const env = agent.client.options?.env;
-    const url = `http://xmtp.chat/dm/${address}?env=${env}`;
-    console.log(`We are online: ${url}`);
+    console.log(`We are online: ${getTestUrl(agent)}`);
 });
 void agent.start();
 //# sourceMappingURL=demo.js.map

package/dist/demo.js.map

@@ -1 +1 @@
-{"version":3,"file":"demo.js","sourceRoot":"","sources":["../src/demo.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AACxC,OAAO,EACL,YAAY,EACZ,UAAU,EACV,MAAM,IAAI,CAAC,EACX,UAAU,GACX,MAAM,kBAAkB,CAAC;AAE1B,MAAM,IAAI,GAAG,UAAU,EAAE,CAAC;AAC1B,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;AAElC,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE;IACvC,MAAM,EAAE,CAAC,IAAI,UAAU,EAAE,CAAC;IAC1B,MAAM,EAAE,IAAI;IACZ,GAAG,EAAE,KAAK;CACX,CAAC,CAAC;AAEH,KAAK,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,EAAE;IAC1B,KAAK,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;AAC/C,CAAC,CAAC,CAAC;AAEH,KAAK,CAAC,EAAE,CACN,SAAS,EACT,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE;IACnD,KAAK,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACvC,KAAK,CAAC,IAAI,EAAE,CAAC;AACf,CAAC,CAAC,CACH,CAAC;AAEF,KAAK,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,EAAE;IAC1B,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;AACnD,CAAC,CAAC,CAAC;AAEH,MAAM,YAAY,GAAG,CAAC,KAAc,EAAE,EAAE;IACtC,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;AACrC,CAAC,CAAC;AAEF,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;AAEhC,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;AAEjC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;IACrB,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,iBAAiB,EAAE,UAAU,CAAC;IAC3D,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC;IACtC,MAAM,GAAG,GAAG,uBAAuB,OAAO,QAAQ,GAAG,EAAE,CAAC;IACxD,OAAO,CAAC,GAAG,CAAC,kBAAkB,GAAG,EAAE,CAAC,CAAC;AACvC,CAAC,CAAC,CAAC;AAEH,KAAK,KAAK,CAAC,KAAK,EAAE,CAAC"}
+{"version":3,"file":"demo.js","sourceRoot":"","sources":["../src/demo.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE3E,IAAI,CAAC;IACH,WAAW,CAAC,MAAM,CAAC,CAAC;IACpB,OAAO,CAAC,IAAI,CAAC,+BAA+B,CAAC,CAAC;AAChD,CAAC;AAAC,MAAM,CAAC,CAAA,CAAC;AAEV,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe;IACvC,CAAC,CAAC,MAAM,KAAK,CAAC,MAAM,EAAE;IACtB,CAAC,CAAC,MAAM,KAAK,CAAC,MAAM,CAAC,YAAY,CAAC,UAAU,EAAE,CAAC,EAAE;QAC7C,MAAM,EAAE,IAAI;KACb,CAAC,CAAC;AAEP,MAAM,MAAM,GAAG,IAAI,aAAa,EAAE,CAAC;AAEnC,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;IACvC,MAAM,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,mBAAmB,EAAE,CAAC,CAAC;AACrE,CAAC,CAAC,CAAC;AAEH,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;AAE/B,KAAK,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,EAAE;IAC1B,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;AACnD,CAAC,CAAC,CAAC;AAEH,KAAK,CAAC,EAAE,CACN,SAAS,EACT,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;IAC/C,MAAM,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;AACrD,CAAC,CAAC,CACH,CAAC;AAEF,MAAM,YAAY,GAAG,CAAC,KAAc,EAAE,EAAE;IACtC,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;AACrC,CAAC,CAAC;AAEF,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;AAEhC,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;AAEjC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;IACrB,OAAO,CAAC,GAAG,CAAC,kBAAkB,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AACrD,CAAC,CAAC,CAAC;AAEH,KAAK,KAAK,CAAC,KAAK,EAAE,CAAC"}

package/dist/middleware/CommandRouter.d.ts

@@ -0,0 +1,10 @@
+import { type AgentEventHandler, type AgentMiddleware } from "../core/Agent.js";
+import type { AgentContext } from "../core/AgentContext.js";
+export declare class CommandRouter<ContentTypes> {
+    private commandMap;
+    private defaultHandler;
+    command(command: string, handler: AgentEventHandler): this;
+    default(handler: AgentEventHandler): this;
+    handle(ctx: AgentContext): Promise<boolean>;
+    middleware: () => AgentMiddleware<ContentTypes>;
+}

package/dist/middleware/CommandRouter.js

@@ -0,0 +1,45 @@
+import { isText } from "../utils/message.js";
+export class CommandRouter {
+    commandMap = new Map();
+    defaultHandler = null;
+    command(command, handler) {
+        if (!command.startsWith("/")) {
+            throw new Error('Command must start with "/"');
+        }
+        this.commandMap.set(command.toLowerCase(), handler);
+        return this;
+    }
+    default(handler) {
+        this.defaultHandler = handler;
+        return this;
+    }
+    async handle(ctx) {
+        if (!isText(ctx.message)) {
+            return false;
+        }
+        const messageText = ctx.message.content;
+        const parts = messageText.split(" ");
+        const command = parts[0].toLowerCase();
+        // Check if this is a command message
+        if (command.startsWith("/")) {
+            const handler = this.commandMap.get(command);
+            if (handler) {
+                await handler(ctx);
+                return true;
+            }
+        }
+        // If no command matched and there's a default handler, use it
+        if (this.defaultHandler) {
+            await this.defaultHandler(ctx);
+            return true;
+        }
+        return false;
+    }
+    middleware = () => async (ctx, next) => {
+        const handled = await this.handle(ctx);
+        if (!handled) {
+            await next();
+        }
+    };
+}
+//# sourceMappingURL=CommandRouter.js.map

package/dist/middleware/CommandRouter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandRouter.js","sourceRoot":"","sources":["../../src/middleware/CommandRouter.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE5C,MAAM,OAAO,aAAa;IAChB,UAAU,GAAG,IAAI,GAAG,EAA6B,CAAC;IAClD,cAAc,GAA6B,IAAI,CAAC;IAExD,OAAO,CAAC,OAAe,EAAE,OAA0B;QACjD,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;QACjD,CAAC;QACD,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,OAAO,CAAC,CAAC;QACpD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,CAAC,OAA0B;QAChC,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC;QAC9B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAiB;QAC5B,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YACzB,OAAO,KAAK,CAAC;QACf,CAAC;QAED,MAAM,WAAW,GAAG,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC;QACxC,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACrC,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;QAEvC,qCAAqC;QACrC,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAC5B,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YAC7C,IAAI,OAAO,EAAE,CAAC;gBACZ,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;gBACnB,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;QAED,8DAA8D;QAC9D,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACxB,MAAM,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;YAC/B,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAED,UAAU,GAAwC,GAAG,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QAC1E,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,EAAE,CAAC;QACf,CAAC;IACH,CAAC,CAAC;CACH"}

package/dist/middleware/index.d.ts

@@ -0,0 +1 @@
+export * from "./CommandRouter.js";

package/dist/middleware/index.js

@@ -0,0 +1,2 @@
+export * from "./CommandRouter.js";
+//# sourceMappingURL=index.js.map

package/dist/middleware/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC"}

package/dist/utils/crypto.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Convert a hex string to a Uint8Array encryption key.
+ * @param hex - The hex string
+ * @returns The encryption key
+ */
+export declare const getEncryptionKeyFromHex: (hex: string) => Uint8Array;
+/**
+ * Generates a complete set of client keys required for XMTP agent initialization.
+ *
+ * Creates both a wallet private key for client authentication and a database
+ * encryption key for secure local storage. The returned keys can be used
+ * directly as environment variables.
+ *
+ * @returns An object containing the keys
+ */
+export declare const generateClientKeys: () => {
+    XMTP_DB_ENCRYPTION_KEY: string;
+    XMTP_WALLET_KEY: `0x${string}`;
+};

package/dist/utils/crypto.js

@@ -0,0 +1,55 @@
+import { getRandomValues } from "node:crypto";
+import { secp256k1 } from "@noble/curves/secp256k1.js";
+import { fromString, toString } from "uint8arrays";
+import { toHex } from "viem";
+/**
+ * Convert a hex string to a Uint8Array encryption key.
+ * @param hex - The hex string
+ * @returns The encryption key
+ */
+export const getEncryptionKeyFromHex = (hex) => {
+    return fromString(hex, "hex");
+};
+/**
+ * Generates a cryptographically secure random private key for wallet operations.
+ *
+ * Uses the secp256k1 elliptic curve to generate a private key suitable for
+ * Ethereum-compatible wallets and XMTP client authentication.
+ *
+ * @returns A hex-encoded private key string (64 characters, prefixed with '0x')
+ */
+function generatePrivateKey() {
+    return toHex(secp256k1.utils.randomSecretKey());
+}
+/**
+ * Generates a cryptographically secure random encryption key for database encryption.
+ *
+ * Creates a 256-bit (32-byte) encryption key using the Node.js crypto module's
+ * secure random number generator.
+ *
+ * @returns A hex-encoded encryption key string (64 characters)
+ */
+const generateEncryptionKeyHex = () => {
+    /* Generate a random encryption key */
+    const uint8Array = getRandomValues(new Uint8Array(32));
+    /* Convert the encryption key to a hex string */
+    return toString(uint8Array, "hex");
+};
+/**
+ * Generates a complete set of client keys required for XMTP agent initialization.
+ *
+ * Creates both a wallet private key for client authentication and a database
+ * encryption key for secure local storage. The returned keys can be used
+ * directly as environment variables.
+ *
+ * @returns An object containing the keys
+ */
+export const generateClientKeys = () => {
+    const walletKey = generatePrivateKey();
+    const dbEncryptionKey = generateEncryptionKeyHex();
+    return {
+        XMTP_DB_ENCRYPTION_KEY: dbEncryptionKey,
+        XMTP_WALLET_KEY: walletKey,
+    };
+};
+//# sourceMappingURL=crypto.js.map

package/dist/utils/crypto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.js","sourceRoot":"","sources":["../../src/utils/crypto.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC;AAE7B;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,GAAW,EAAc,EAAE;IACjE,OAAO,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;AAChC,CAAC,CAAC;AAEF;;;;;;;GAOG;AACH,SAAS,kBAAkB;IACzB,OAAO,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,eAAe,EAAE,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,wBAAwB,GAAG,GAAG,EAAE;IACpC,sCAAsC;IACtC,MAAM,UAAU,GAAG,eAAe,CAAC,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;IACvD,gDAAgD;IAChD,OAAO,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;AACrC,CAAC,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,EAAE;IACrC,MAAM,SAAS,GAAG,kBAAkB,EAAE,CAAC;IACvC,MAAM,eAAe,GAAG,wBAAwB,EAAE,CAAC;IACnD,OAAO;QACL,sBAAsB,EAAE,eAAe;QACvC,eAAe,EAAE,SAAS;KAC3B,CAAC;AACJ,CAAC,CAAC"}

package/dist/utils/debug.d.ts

@@ -0,0 +1,10 @@
+import { Client } from "@xmtp/node-sdk";
+import type { Agent } from "../core/Agent.js";
+export declare const logDetails: <ContentTypes>(client: Client<ContentTypes>) => Promise<void>;
+/**
+ * Returns a URL to test your agent on https://xmtp.chat/ (for development purposes only).
+ *
+ * @param agent - Your agent instance
+ * @returns The URL to test your agent with
+ */
+export declare const getTestUrl: <ContentTypes>(agent: Agent<ContentTypes>) => string;

package/dist/utils/debug.js

@@ -0,0 +1,53 @@
+import { Client } from "@xmtp/node-sdk";
+export const logDetails = async (client) => {
+    const xmtp = `\x1b[38;2;252;76;52m
+    ██╗  ██╗███╗   ███╗████████╗██████╗ 
+    ╚██╗██╔╝████╗ ████║╚══██╔══╝██╔══██╗
+     ╚███╔╝ ██╔████╔██║   ██║   ██████╔╝
+     ██╔██╗ ██║╚██╔╝██║   ██║   ██╔═══╝ 
+    ██╔╝ ██╗██║ ╚═╝ ██║   ██║   ██║     
+    ╚═╝  ╚═╝╚═╝     ╚═╝   ╚═╝   ╚═╝     
+  \x1b[0m`;
+    const clientsByAddress = client.accountIdentifier?.identifier;
+    const inboxId = client.inboxId;
+    const installationId = client.installationId;
+    const environments = client.options?.env ?? "dev";
+    const urls = [`http://xmtp.chat/dm/${clientsByAddress}`];
+    const conversations = await client.conversations.list();
+    const inboxState = await client.preferences.inboxState();
+    const keyPackageStatuses = await client.getKeyPackageStatusesForInstallationIds([installationId]);
+    let createdDate = new Date();
+    let expiryDate = new Date();
+    // Extract key package status for the specific installation
+    const keyPackageStatus = keyPackageStatuses[installationId] ?? {};
+    if (keyPackageStatus.lifetime) {
+        createdDate = new Date(Number(keyPackageStatus.lifetime.notBefore) * 1000);
+        expiryDate = new Date(Number(keyPackageStatus.lifetime.notAfter) * 1000);
+    }
+    console.log(`
+    ${xmtp}
+    
+    ✓ XMTP Client:
+    • InboxId: ${inboxId}
+    • Version: ${Client.version}
+    • Address: ${clientsByAddress}
+    • Conversations: ${conversations.length}
+    • Installations: ${inboxState.installations.length}
+    • InstallationId: ${installationId}
+    • Key Package created: ${createdDate.toLocaleString()}
+    • Key Package valid until: ${expiryDate.toLocaleString()}
+    • Networks: ${environments}
+    ${urls.map((url) => `• URL: ${url}`).join("\n")}`);
+};
+/**
+ * Returns a URL to test your agent on https://xmtp.chat/ (for development purposes only).
+ *
+ * @param agent - Your agent instance
+ * @returns The URL to test your agent with
+ */
+export const getTestUrl = (agent) => {
+    const address = agent.client.accountIdentifier?.identifier;
+    const env = agent.client.options?.env ?? "dev";
+    return `http://xmtp.chat/dm/${address}?env=${env}`;
+};
+//# sourceMappingURL=debug.js.map

package/dist/utils/debug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.js","sourceRoot":"","sources":["../../src/utils/debug.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAGxC,MAAM,CAAC,MAAM,UAAU,GAAG,KAAK,EAC7B,MAA4B,EAC5B,EAAE;IACF,MAAM,IAAI,GAAG;;;;;;;UAOL,CAAC;IAET,MAAM,gBAAgB,GAAG,MAAM,CAAC,iBAAiB,EAAE,UAAU,CAAC;IAC9D,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAC/B,MAAM,cAAc,GAAG,MAAM,CAAC,cAAc,CAAC;IAC7C,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,EAAE,GAAG,IAAI,KAAK,CAAC;IAElD,MAAM,IAAI,GAAG,CAAC,uBAAuB,gBAAgB,EAAE,CAAC,CAAC;IAEzD,MAAM,aAAa,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC;IACxD,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,UAAU,EAAE,CAAC;IACzD,MAAM,kBAAkB,GACtB,MAAM,MAAM,CAAC,uCAAuC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC;IAEzE,IAAI,WAAW,GAAG,IAAI,IAAI,EAAE,CAAC;IAC7B,IAAI,UAAU,GAAG,IAAI,IAAI,EAAE,CAAC;IAE5B,2DAA2D;IAC3D,MAAM,gBAAgB,GAAG,kBAAkB,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC;IAClE,IAAI,gBAAgB,CAAC,QAAQ,EAAE,CAAC;QAC9B,WAAW,GAAG,IAAI,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,QAAQ,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,CAAC;QAC3E,UAAU,GAAG,IAAI,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,CAAC,GAAG,CAAC;MACR,IAAI;;;iBAGO,OAAO;iBACP,MAAM,CAAC,OAAO;iBACd,gBAAgB;uBACV,aAAa,CAAC,MAAM;uBACpB,UAAU,CAAC,aAAa,CAAC,MAAM;wBAC9B,cAAc;6BACT,WAAW,CAAC,cAAc,EAAE;iCACxB,UAAU,CAAC,cAAc,EAAE;kBAC1C,YAAY;MACxB,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,UAAU,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACvD,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAe,KAA0B,EAAE,EAAE;IACrE,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,iBAAiB,EAAE,UAAU,CAAC;IAC3D,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,IAAI,KAAK,CAAC;IAC/C,OAAO,uBAAuB,OAAO,QAAQ,GAAG,EAAE,CAAC;AACrD,CAAC,CAAC"}

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.
  */
@@ -11,6 +11,13 @@ export type MessageFilter<ContentTypes> = (message: DecodedMessage, client: Clie
  * @returns Filter function
  */
 declare function fromSender<ContentTypes>(senderInboxId: string | string[]): MessageFilter<ContentTypes>;
+/**
+ * Creates a filter that matches text messages starting with a specific string.
+ *
+ * @param prefix - The string prefix to match against
+ * @returns Filter function
+ */
+declare function startsWith<ContentTypes>(prefix: string): MessageFilter<ContentTypes>;
 /**
  * Creates a filter that requires all provided filters to pass
  *
@@ -40,6 +47,17 @@ export declare const filter: {
     fromSelf: MessageFilter<unknown>;
     textOnly: MessageFilter<unknown>;
     fromSender: typeof fromSender;
+    startsWith: typeof startsWith;
+    and: typeof and;
+    or: typeof or;
+    not: typeof not;
+};
+export declare const f: {
+    notFromSelf: MessageFilter<unknown>;
+    fromSelf: MessageFilter<unknown>;
+    textOnly: MessageFilter<unknown>;
+    fromSender: typeof fromSender;
+    startsWith: typeof startsWith;
     and: typeof and;
     or: typeof or;
     not: typeof not;

package/dist/utils/filter.js

@@ -1,4 +1,5 @@
 import { ContentTypeText } from "@xmtp/content-type-text";
+import { getTextContent } from "./message.js";
 /**
  * Creates a filter that excludes messages from the agent itself.
  *
@@ -43,6 +44,18 @@ function fromSender(senderInboxId) {
         return senderIds.includes(message.senderInboxId);
     };
 }
+/**
+ * Creates a filter that matches text messages starting with a specific string.
+ *
+ * @param prefix - The string prefix to match against
+ * @returns Filter function
+ */
+function startsWith(prefix) {
+    return (message) => {
+        const text = getTextContent(message);
+        return !!(text && text.startsWith(prefix));
+    };
+}
 /**
  * Creates a filter that requires all provided filters to pass
  *
@@ -96,11 +109,13 @@ export const filter = {
     textOnly: textOnly(),
     // factory functions
     fromSender,
+    startsWith,
     // combinators
     and,
     or,
     not,
 };
+export const f = filter;
 export const withFilter = (filter, listener) => (ctx) => {
     if (filter(ctx.message, ctx.client)) {
         listener(ctx);

package/dist/utils/filter.js.map

@@ -1 +1 @@
-{"version":3,"file":"filter.js","sourceRoot":"","sources":["../../src/utils/filter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAY1D;;;;GAIG;AACH,SAAS,WAAW;IAClB,OAAO,CAAC,OAAuB,EAAE,MAA4B,EAAE,EAAE;QAC/D,OAAO,OAAO,CAAC,aAAa,KAAK,MAAM,CAAC,OAAO,CAAC;IAClD,CAAC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,QAAQ;IACf,OAAO,CAAC,OAAuB,EAAE,MAA4B,EAAE,EAAE;QAC/D,OAAO,OAAO,CAAC,aAAa,KAAK,MAAM,CAAC,OAAO,CAAC;IAClD,CAAC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,QAAQ;IACf,OAAO,CAAC,OAAuB,EAAE,EAAE;QACjC,OAAO,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,MAAM,CAAC,eAAe,CAAC,CAAC;IACxD,CAAC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,UAAU,CACjB,aAAgC;IAEhC,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC;QAC5C,CAAC,CAAC,aAAa;QACf,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC;IAEpB,OAAO,CAAC,OAAuB,EAAE,EAAE;QACjC,OAAO,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;IACnD,CAAC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,GAAG,CACV,GAAG,OAAsC;IAEzC,OAAO,CAAC,OAAuB,EAAE,MAA4B,EAAE,EAAE;QAC/D,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YACvC,IAAI,CAAC,MAAM;gBAAE,OAAO,KAAK,CAAC;QAC5B,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,EAAE,CACT,GAAG,OAAsC;IAEzC,OAAO,CAAC,OAAuB,EAAE,MAA4B,EAAE,EAAE;QAC/D,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YACvC,IAAI,MAAM;gBAAE,OAAO,IAAI,CAAC;QAC1B,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,GAAG,CACV,MAAmC;IAEnC,OAAO,CAAC,OAAuB,EAAE,MAA4B,EAAE,EAAE;QAC/D,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAClC,CAAC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,gBAAgB;IAChB,WAAW,EAAE,WAAW,EAAE;IAC1B,QAAQ,EAAE,QAAQ,EAAE;IACpB,QAAQ,EAAE,QAAQ,EAAE;IACpB,oBAAoB;IACpB,UAAU;IACV,cAAc;IACd,GAAG;IACH,EAAE;IACF,GAAG;CACJ,CAAC;AAEF,MAAM,CAAC,MAAM,UAAU,GACrB,CACE,MAAmC,EACnC,QAAmD,EACnD,EAAE,CACJ,CAAC,GAA+B,EAAE,EAAE;IAClC,IAAI,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QACpC,QAAQ,CAAC,GAAG,CAAC,CAAC;IAChB,CAAC;AACH,CAAC,CAAC"}
+{"version":3,"file":"filter.js","sourceRoot":"","sources":["../../src/utils/filter.ts"],"names":[],"mappings":"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"}

package/dist/utils/index.d.ts

@@ -1,2 +1,4 @@
+export * from "./crypto.js";
 export * from "./filter.js";
+export * from "./message.js";
 export * from "./user.js";

package/dist/utils/index.js

@@ -1,3 +1,5 @@
+export * from "./crypto.js";
 export * from "./filter.js";
+export * from "./message.js";
 export * from "./user.js";
 //# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}

package/dist/utils/message.d.ts

@@ -0,0 +1,35 @@
+import { type Reaction } from "@xmtp/content-type-reaction";
+import { type RemoteAttachment } from "@xmtp/content-type-remote-attachment";
+import { type Reply } from "@xmtp/content-type-reply";
+import type { DecodedMessage } from "@xmtp/node-sdk";
+type ContentMessage = Pick<DecodedMessage, "content" | "contentType" | "fallback">;
+export declare const isReaction: <M extends ContentMessage>(m: M) => m is M & {
+    content: Reaction;
+};
+export declare const isReply: <M extends ContentMessage>(m: M) => m is M & {
+    content: Reply;
+};
+export declare const isTextReply: <M extends ContentMessage>(m: M) => m is M & {
+    content: Reply & {
+        content: string;
+    };
+};
+export declare const isText: <M extends ContentMessage>(m: M) => m is M & {
+    content: string;
+};
+export declare const isRemoteAttachment: <M extends ContentMessage>(m: M) => m is M & {
+    content: RemoteAttachment;
+};
+/**
+ * Extracts the text content from various XMTP message types.
+ *
+ * Supports extracting text from:
+ * - Text messages: Returns the direct string content
+ * - Text replies: Returns the reply content text
+ * - Reactions: Returns the reaction content (emoji/text)
+ *
+ * @param message - The decoded message to extract text from
+ * @returns The text content as a string, or `undefined` for message types that don't contain extractable text content
+ */
+export declare const getTextContent: (message: ContentMessage) => string | undefined;
+export {};

package/dist/utils/message.js

@@ -0,0 +1,30 @@
+import { ContentTypeReaction, } from "@xmtp/content-type-reaction";
+import { ContentTypeRemoteAttachment, } from "@xmtp/content-type-remote-attachment";
+import { ContentTypeReply } from "@xmtp/content-type-reply";
+import { ContentTypeText } from "@xmtp/content-type-text";
+export const isReaction = (m) => !!m.contentType?.sameAs(ContentTypeReaction);
+export const isReply = (m) => !!m.contentType?.sameAs(ContentTypeReply);
+export const isTextReply = (m) => isReply(m) && typeof m.content.content === "string";
+export const isText = (m) => !!m.contentType?.sameAs(ContentTypeText);
+export const isRemoteAttachment = (m) => !!m.contentType?.sameAs(ContentTypeRemoteAttachment);
+/**
+ * Extracts the text content from various XMTP message types.
+ *
+ * Supports extracting text from:
+ * - Text messages: Returns the direct string content
+ * - Text replies: Returns the reply content text
+ * - Reactions: Returns the reaction content (emoji/text)
+ *
+ * @param message - The decoded message to extract text from
+ * @returns The text content as a string, or `undefined` for message types that don't contain extractable text content
+ */
+export const getTextContent = (message) => {
+    switch (true) {
+        case isReaction(message):
+        case isTextReply(message):
+            return message.content.content;
+        case isText(message):
+            return message.content;
+    }
+};
+//# sourceMappingURL=message.js.map

package/dist/utils/message.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.js","sourceRoot":"","sources":["../../src/utils/message.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,GAEpB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,2BAA2B,GAE5B,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAc,MAAM,0BAA0B,CAAC;AACxE,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAQ1D,MAAM,CAAC,MAAM,UAAU,GAAG,CACxB,CAAI,EAC4B,EAAE,CAClC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,mBAAmB,CAAC,CAAC;AAE/C,MAAM,CAAC,MAAM,OAAO,GAAG,CACrB,CAAI,EACyB,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,gBAAgB,CAAC,CAAC;AAE5E,MAAM,CAAC,MAAM,WAAW,GAAG,CACzB,CAAI,EAC+C,EAAE,CACrD,OAAO,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,OAAO,CAAC,OAAO,KAAK,QAAQ,CAAC;AAEtD,MAAM,CAAC,MAAM,MAAM,GAAG,CACpB,CAAI,EAC0B,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,eAAe,CAAC,CAAC;AAE5E,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,CAAI,EACoC,EAAE,CAC1C,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,2BAA2B,CAAC,CAAC;AAEvD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,OAAuB,EAAE,EAAE;IACxD,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,UAAU,CAAC,OAAO,CAAC,CAAC;QACzB,KAAK,WAAW,CAAC,OAAO,CAAC;YACvB,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC;QACjC,KAAK,MAAM,CAAC,OAAO,CAAC;YAClB,OAAO,OAAO,CAAC,OAAO,CAAC;IAC3B,CAAC;AACH,CAAC,CAAC"}

package/package.json

@@ -4,8 +4,13 @@
     "url": "https://github.com/xmtp/xmtp-js/issues"
   },
   "dependencies": {
-    "@xmtp/content-type-reply": "^2.0.2",
-    "@xmtp/node-sdk": "^4.0.3",
+    "@noble/curves": "^2.0.0",
+    "@xmtp/content-type-reaction": "workspace:^",
+    "@xmtp/content-type-remote-attachment": "workspace:^",
+    "@xmtp/content-type-reply": "workspace:^",
+    "@xmtp/content-type-text": "workspace:^",
+    "@xmtp/node-sdk": "workspace:^",
+    "uint8arrays": "^5.1.0",
     "viem": "^2.31.7"
   },
   "description": "XMTP Agent SDK for interacting with XMTP networks",
@@ -13,6 +18,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,15 +59,17 @@
     "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",
+    "demo": "tsx src/demo.ts",
     "dev": "tsx --watch src/main.ts",
-    "start": "tsx src/demo.ts",
-    "test": "vitest --typecheck",
+    "gen:keys": "tsx src/bin/generateKeys.ts",
+    "start": "yarn demo",
+    "test": "yarn typecheck && vitest --typecheck",
     "test:cov": "vitest run --coverage",
     "typecheck": "tsc --noEmit"
   },
   "type": "module",
-  "version": "0.0.3"
+  "version": "0.0.5"
 }