towns-agent 2.0.4 → 2.0.6

package/templates/quickstart/AGENTS.md

@@ -0,0 +1,267 @@
+# AGENTS.md
+
+This file provides guidance to AI agents for building Towns Protocol bots.
+
+## Quick Start
+
+**Requirements:**
+1. **APP_PRIVATE_DATA** - Bot credentials
+2. **JWT_SECRET** - Webhook security token
+3. **Event handlers** - Functions responding to Towns events
+
+**CRITICAL:** Stateless architecture - no message history, thread context, or conversation memory. Store context externally if needed.
+
+## Base Payload
+
+All event handlers receive a `BasePayload`:
+
+```typescript
+type BasePayload = {
+    userId: string      // Hex address (0x...)
+    channelId: string
+    eventId: string     // Unique event ID (use as threadId/replyId when responding)
+    createdAt: Date
+    event: StreamEvent
+    isDm: boolean       // true if the event is from a DM
+    isGdm: boolean      // true if the event is from a GDM
+}
+```
+
+**Example:**
+```typescript
+bot.onMessage(async (handler, event) => {
+  if (event.isDm) {
+    console.log('DM')
+  } else if (event.isGdm) {
+    console.log('GDM')
+  }
+})
+```
+
+## Event Handlers
+
+### onMessage
+**When:** Any non-slash-command message
+
+```typescript
+{
+  ...basePayload,
+  message: string,
+  replyId?: string,         // EventId of replied message
+  threadId?: string,        // EventId of thread start
+  isMentioned: boolean,
+  mentions: Array<{ userId: string, displayName: string }>
+}
+
+bot.onMessage(async (handler, event) => {
+  if (event.isMentioned) {
+    await handler.sendMessage(event.channelId, "You mentioned me!")
+  }
+  if (event.threadId) {
+    await handler.sendMessage(event.channelId, "Reply", { threadId: event.threadId })
+  }
+})
+```
+
+### onSlashCommand
+**When:** User types `/command args` (does NOT trigger onMessage)
+
+```typescript
+{
+  ...basePayload,
+  command: string,
+  args: string[],
+  mentions: Array<{ userId: string, displayName: string }>,
+  replyId?: string,
+  threadId?: string
+}
+```
+
+**Setup:**
+```typescript
+// 1. src/commands.ts
+import type { AgentCommand } from '@towns-labs/agent'
+
+export const commands = [
+  { name: "help", description: "Show help" }
+] as const satisfies AgentCommand[]
+
+// 2. Initialize
+const bot = await makeTownsAgent(privateData, jwtSecret, { commands })
+
+// 3. Register
+bot.onSlashCommand("help", async (handler, event) => {
+  await handler.sendMessage(event.channelId, "Commands: /help")
+})
+```
+
+#### Paid Commands
+Add a `paid` property to your command definition with a price in USDC:
+```typescript
+{ name: "generate", description: "Generate AI content", paid: { price: '$0.20' } }
+```
+
+### onReaction
+**When:** User adds emoji reaction
+
+```typescript
+{
+  ...basePayload,
+  reaction: string,        // "thumbsup", "heart"
+  messageId: string        // EventId
+}
+```
+**Note:** No access to original message content.
+
+### onInteractionResponse
+**When:** Button click, form submit, transaction/signature response
+**Pattern:** Set ID in request -> Match ID in response
+
+```typescript
+{ ...basePayload, response: DecryptedInteractionResponse }
+
+// 1. Send request with ID
+await handler.sendInteractionRequest(channelId, {
+  type: 'form',
+  id: "confirm-action",
+  title: "Confirm?",
+  components: [{ id: "yes", component: { case: "button", value: { label: "Yes" } } }]
+}, hexToBytes(userId as `0x${string}`))
+
+// 2. Match ID in response
+bot.onInteractionResponse(async (handler, event) => {
+  if (event.response.payload.content?.case === "form") {
+    const form = event.response.payload.content.value
+    if (form.requestId === "confirm-action") {
+      for (const c of form.components) {
+        if (c.component.case === "button" && c.id === "yes") {
+          await handler.sendMessage(event.channelId, "Confirmed!")
+        }
+      }
+    }
+  }
+})
+```
+
+**Other Request Types:**
+```typescript
+import { hexToBytes } from 'viem'
+
+// Transaction
+await handler.sendInteractionRequest(channelId, {
+  type: 'transaction',
+  id: "tx-id",
+  title: "Send USDC",
+  content: {
+    case: "evm",
+    value: { chainId: "8453", to, value: "0", data, signerWallet: undefined }
+  }
+})
+
+// Signature
+await handler.sendInteractionRequest(channelId, {
+  type: 'signature',
+  id: "sig-id",
+  title: "Sign",
+  chainId: "8453",
+  data: JSON.stringify(typedData),
+  signatureType: InteractionRequestPayload_Signature_SignatureType.TYPED_DATA,
+  signerWallet: undefined
+})
+```
+
+### Other Events
+
+**onMessageEdit:** `{ ...basePayload, refEventId: string, message: string, ... }`
+
+**onRedaction / onEventRevoke:** `{ ...basePayload, refEventId: string }`
+
+**onChannelJoin / onChannelLeave:** Base payload only
+
+**onStreamEvent:** `{ ...basePayload, event: ParsedEvent }` (advanced)
+
+## Handler API
+
+**Types:** `AgentHandler`, `BasePayload`, `AgentCommand`
+
+```typescript
+// Send (use @userId to mention a user in message text, and add mentions in sendMessage options)
+await handler.sendMessage(channelId, "Hello @0x123...", {
+  threadId?, replyId?, mentions: [{ userId: "0x123...", displayName: "name" }], attachments? })
+
+await handler.editMessage(channelId, messageId, newMessage)  // Bot's own only
+await handler.sendReaction(channelId, messageId, reaction)
+await handler.sendGM(channelId, typeUrl, data)               // Send typed generic message
+await handler.sendRawGM(channelId, typeUrl, rawBytes)         // Send raw generic message bytes
+await handler.pinMessage(channelId, eventId, streamEvent)
+await handler.unpinMessage(channelId, eventId)
+await handler.removeEvent(channelId, eventId)                 // Bot's own
+await handler.sendKeySolicitation(channelId)
+await handler.uploadDeviceKeys()
+await handler.sendBlockchainTransaction(channelId, params)
+```
+
+## Attachments
+
+```typescript
+// Image
+attachments: [{ type: 'image', url: 'https://...jpg', alt: 'Desc' }]
+
+// Link
+attachments: [{ type: 'link', url: 'https://...' }]
+
+// Miniapp
+attachments: [{ type: 'miniapp', url: 'https://...' }]
+
+// Chunked (videos, screenshots)
+import { readFileSync } from 'node:fs'
+attachments: [{
+  type: 'chunked',
+  data: readFileSync('./video.mp4'),  // Uint8Array
+  filename: 'video.mp4',
+  mimetype: 'video/mp4',  // Required
+  width: 1920,            // Optional
+  height: 1080
+}]
+```
+
+## Web3 / Contract Interactions
+
+### Agent Wallet Architecture
+**Single wallet** using ERC-7702 delegation. The agent has one address (`bot.appAddress`) that acts as both the signer (EOA) and the smart account. The agent owner (the account that registered the app) is a **super admin** of this wallet, retaining full control.
+
+```typescript
+bot.viem, bot.appAddress  // Access points
+
+// Reading
+import { readContract } from 'viem/actions'
+const result = await readContract(bot.viem, { address, abi, functionName: 'balanceOf', args: [user] })
+```
+
+### Writing
+```typescript
+import { writeContract } from 'viem/actions'
+const hash = await writeContract(bot.viem, { address: targetContract, abi,
+  functionName: 'transfer', args: [recipient, amount] })
+```
+
+## External Interactions (Unprompted Messages)
+
+`bot.start()` returns a **Hono app**. To extend with additional routes, create a new Hono app and use `.route('/', app)` per https://hono.dev/docs/guides/best-practices#building-a-larger-application
+
+**All handler methods available on bot** (webhooks, timers, tasks):
+You need data prior (channelId, etc):
+```typescript
+bot.sendMessage(channelId, msg, opts?) | bot.editMessage(...) | bot.sendReaction(...) | bot.removeEvent(...)
+bot.adminRemoveEvent(...) | bot.pinMessage(...) | bot.unpinMessage(...)
+// Properties: bot.viem, bot.appAddress
+```
+
+**Patterns:** Store channel IDs | Webhooks/timers | Call bot.* directly | Handle errors
+
+## Critical Notes
+
+1. **User IDs are addresses** - `0x...`, not usernames
+2. **Use `@userId` for mentions** and add mentions in sendMessage options
+3. **Slash commands exclusive** - Never trigger `onMessage`
+4. **Stateless** - Store context externally

package/templates/quickstart/README.md

@@ -0,0 +1,95 @@
+# Towns Agent
+
+A [Towns Protocol](https://towns.com) agent built with [`@towns-labs/agent`](https://www.npmjs.com/package/@towns-labs/agent).
+
+## Getting Started
+
+### 1. Install dependencies
+
+```bash
+bun install
+```
+
+### 2. Create an agent account
+
+```bash
+bunx towns-agent create --env prod
+```
+
+This will prompt for authentication and bot metadata, then output your credentials. Pipe them straight into `.env`:
+
+```bash
+bunx towns-agent create --env prod >> .env
+```
+
+Or copy `.env.sample` and fill in the values manually:
+
+```bash
+cp .env.sample .env
+```
+
+| Variable | Description |
+|---|---|
+| `APP_ADDRESS` | Agent app address |
+| `APP_PRIVATE_DATA` | Agent credentials |
+| `JWT_SECRET` | Webhook security token |
+| `PORT` | Server port (default: 5123) |
+
+### 3. Start the agent
+
+```bash
+bun run dev
+```
+
+### 4. Register your webhook
+
+Once the server is running, register its URL so Towns can deliver events:
+
+```bash
+bunx towns-agent setup
+```
+
+This reads the app address from your `.env` and prompts for the webhook URL and notification settings.
+
+### 5. View or update metadata
+
+```bash
+# View current metadata
+bunx towns-agent metadata view
+
+# Update metadata interactively
+bunx towns-agent metadata update
+```
+
+## Project Structure
+
+```
+src/
+  index.ts       # Agent initialization and event handlers
+  commands.ts    # Slash command definitions
+```
+
+- **`commands.ts`** — Define slash commands that appear in autocomplete.
+- **`index.ts`** — Initialize the agent with `makeTownsAgent` and register event handlers (`onMessage`, `onSlashCommand`, etc.).
+
+## Scripts
+
+| Script | Description |
+|---|---|
+| `bun run dev` | Start with hot-reload |
+| `bun run start` | Start without hot-reload |
+| `bun run build` | Type-check |
+| `bun run lint` | Lint with oxlint |
+| `bun run fmt` | Format with oxfmt |
+| `bun run fmt:check` | Check formatting |
+
+## Updating
+
+```bash
+bunx towns-agent update
+```
+
+## Resources
+
+- [AGENTS.md](./AGENTS.md) — API reference for event handlers, payloads, and handler methods
+- [@towns-labs/agent on npm](https://www.npmjs.com/package/@towns-labs/agent)

package/templates/quickstart/_gitignore

@@ -0,0 +1,33 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+
+# Environment variables
+.env
+.env.local
+.env.production
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Coverage directory used by tools like istanbul
+coverage/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db

package/templates/quickstart/package.json

@@ -0,0 +1,35 @@
+{
+    "name": "towns-agent-quickstart",
+    "private": true,
+    "version": "0.0.1",
+    "type": "module",
+    "main": "src/index.ts",
+    "scripts": {
+        "build": "tsc --noEmit",
+        "dev": "bun run --watch src/index.ts",
+        "fmt": "oxfmt --write ./src",
+        "fmt:check": "oxfmt --check ./src",
+        "lint": "oxlint ./src",
+        "lint:fix": "oxlint ./src --fix",
+        "start": "bun run src/index.ts"
+    },
+    "dependencies": {
+        "@connectrpc/connect-node": "^2.1.0",
+        "@hono/node-server": "^1.19.9",
+        "@towns-labs/agent": "workspace:^",
+        "@towns-labs/proto": "workspace:^",
+        "dotenv": "^16.4.5",
+        "hono": "^4.11.7",
+        "viem": "2.45.1"
+    },
+    "devDependencies": {
+        "@types/bun": "^1.3.1",
+        "@types/node": "^20.14.8",
+        "oxfmt": "^0.1.0",
+        "oxlint": "^1.41.0",
+        "typescript": "~5.8.3"
+    },
+    "files": [
+        "/dist"
+    ]
+}

package/templates/quickstart/src/commands.ts

@@ -0,0 +1,12 @@
+import type { AgentCommand } from "@towns-labs/agent"
+
+// Those commands will be registered to the bot as soon as the bot is initialized
+// and will be available in the slash command autocomplete.
+const commands = [
+  {
+    name: "help",
+    description: "Get help with bot commands",
+  },
+] as const satisfies AgentCommand[]
+
+export default commands

package/templates/quickstart/src/index.ts

@@ -0,0 +1,56 @@
+import "dotenv/config"
+import { serve } from "@hono/node-server"
+import { makeTownsAgent } from "@towns-labs/agent"
+import { createServer } from "node:http2"
+import commands from "./commands"
+
+const bot = await makeTownsAgent(
+  process.env.APP_PRIVATE_DATA!,
+  process.env.JWT_SECRET!,
+  { commands },
+)
+
+bot.onSlashCommand("help", async (handler, { channelId }) => {
+  await handler.sendMessage(
+    channelId,
+    "**Available Commands:**\n\n" +
+      "• `/help` - Show this help message\n" +
+      "**Message Triggers:**\n\n" +
+      "• React with 👋 - I'll wave back\n" +
+      '• Say "hello" or "hey" - I\'ll greet you back\n' +
+      '• Say "ping" - I\'ll show latency\n' +
+      '• Say "react" - I\'ll add a reaction\n',
+  )
+})
+
+bot.onMessage(async (handler, { message, channelId, eventId, createdAt }) => {
+  if (message.includes("hello") || message.includes("hey")) {
+    await handler.sendMessage(channelId, "Hello there! 👋")
+    return
+  }
+  if (message.includes("ping")) {
+    const now = new Date()
+    await handler.sendMessage(
+      channelId,
+      `Pong! 🏓 ${now.getTime() - createdAt.getTime()}ms`,
+    )
+    return
+  }
+  if (message.includes("react")) {
+    await handler.sendReaction(channelId, eventId, "👍")
+    return
+  }
+})
+
+bot.onReaction(async (handler, { reaction, channelId }) => {
+  if (reaction === "👋") {
+    await handler.sendMessage(channelId, "I saw your wave! 👋")
+  }
+})
+
+const app = bot.start()
+serve({
+  fetch: app.fetch,
+  port: Number(process.env.PORT) || 5123,
+  createServer,
+})

package/templates/quickstart/tsconfig.json

@@ -0,0 +1,25 @@
+{
+    "compilerOptions": {
+        "target": "esnext",
+        "module": "esnext",
+        "moduleResolution": "bundler",
+        "resolveJsonModule": true,
+        "declaration": true,
+        "declarationMap": true,
+        "sourceMap": true,
+        "isolatedModules": true,
+        "allowSyntheticDefaultImports": true,
+        "esModuleInterop": true,
+        "forceConsistentCasingInFileNames": true,
+        "strict": true,
+        "noImplicitAny": true,
+        "strictNullChecks": true,
+        "alwaysStrict": true,
+        "noImplicitReturns": true,
+        "noFallthroughCasesInSwitch": true,
+        "skipLibCheck": true,
+        "outDir": "./dist",
+        "types": ["node"]
+    },
+    "include": ["src/**/*"]
+}