SuperDapp Agents SDK for Node.js/TypeScript

A professional-grade Node.js/TypeScript SDK and CLI for building AI agents on the SuperDapp platform. This SDK provides a unified interface for creating intelligent bots that can interact with users, handle commands, and integrate with multiple large language models.

🚀 Webhook-Based Agent Architecture

SuperDapp agents use a webhook-based architecture for maximum portability and simplicity.

• Centralized command/message routing in the SDK runtime
• Lightweight lifecycle: you instantiate an agent, register handlers, and pass incoming webhook bodies to it
• Pluggable command and message handlers
• Interactive UI support (buttons, multiselect, reply markup)
• Event dispatch built-in (CommandRegistry + WebhookAgent handle command routing and generic messages)
• Signature validation is application-level: validate incoming requests (e.g., in your Express/Worker handler) before calling agent.processRequest
• Works with any HTTP hosting (Node.js, serverless, etc.)

This is the default architecture for all SuperDapp agents.

🆕 Latest Updates

v1.0.0 - Production Ready Release

• ✅ Complete Webhook Support - Full webhook-based agent architecture
• ✅ Enhanced CLI - New create command and improved project management
• ✅ Interactive UI - Advanced button layouts and multiselect support
• ✅ Multi-Platform Deployment - Cloudflare Workers, AWS Lambda and Docker
• ✅ Comprehensive Documentation - Complete guides and API reference
• ✅ TypeScript Support - Full type safety and IntelliSense
• ✅ Testing Framework - Jest setup with utilities and mocks

🚦 CLI Usage

Project Initialization

You can now use a positional argument for the project directory:

superdapp create my-awesome-agent

Example

superdapp create my-agent
cd my-agent
npm install
superdapp configure
superdapp run

🧑‍💻 CLI Commands

• superdapp create [directory] – Create a new agent project (supports positional or --name)
• superdapp configure – Configure API keys and environment variables
• superdapp run – Run the agent locally for testing (supports multiple environment file formats)

Environment File Support

The superdapp run command automatically detects your runtime and supports multiple environment file formats:

• Node.js: .env files
• AWS Lambda: env.json files
• Cloudflare Workers: .dev.vars files

The CLI auto-detects formats; see docs/CLI Guide for details.

🎯 Features

• 🤖 Model-Agnostic AI Integration: Seamlessly work with OpenAI, Gemini, Claude, and other LLMs
• 💬 Real-time Messaging: Built-in support for channels and direct messages
• 🔧 CLI Tools: AWS Amplify-inspired CLI for project management and deployment
• 📱 Command Handling: Structured command routing and message processing
• 🔄 Webhook Architecture: Modern webhook-based agent architecture
• 🎨 Interactive UI: Support for buttons, multiselect, and reply markup
• ⚡ Serverless Ready: Ready for deployment to various platforms
• 🛠️ TypeScript First: Full type safety with comprehensive TypeScript support
• 🧪 Testing Ready: Jest setup with comprehensive test utilities

📦 Installation

Using npm

npm install @superdapp/agents

Using yarn

yarn add @superdapp/agents

Using pnpm

pnpm add @superdapp/agents

🛠️ Development

For local development and testing, see DEVELOPMENT.md for instructions on setting up the development environment using npm link.

For advanced development patterns and best practices, see our API Reference.

Global CLI Installation

npm install -g @superdapp/agents

📚 Documentation

For comprehensive documentation, visit our Documentation Hub:

• Quick Start Guide - Get up and running in minutes
• CLI Guide - Complete command-line interface documentation
• API Reference - Complete SDK reference
• Deployment Guide - Deploy to production
• Tunneling (ngrok) - Expose your local webhook

🔧 Advanced Usage

API Client Coverage

The SDK client currently covers the core messaging flows:

• Channel and connection messages (send, update, delete)
• Join/leave social groups
• Fetch bot info and user channels

Additional endpoints (media uploads, reactions, typing status, etc.) can be added incrementally; open an issue if you need one prioritized.

See the API reference and /examples for details.

Scheduled Tasks

Integrate with node-schedule for periodic tasks:

import { schedule } from '@superdapp/agents';

// Schedule daily news updates
schedule.scheduleJob('0 9 * * *', async () => {
  const news = await generateDailyNews();
  await agent.sendChannelMessage('news-channel', news);
});

Error Handling

The client includes Axios interceptors for basic request/response logging and error propagation. Wrap your command handlers in try/catch and surface actionable messages to users as needed.

Type Safety

Full TypeScript support with comprehensive types:

import type {
  MessageData,
  CommandHandler,
  BotConfig,
  ApiResponse,
} from '@superdapp/agents';

const handleCommand: CommandHandler = async ({
  message,
  replyMessage,
  roomId,
}) => {
  // Fully typed message object
  const messageText = (message.body as any)?.m?.body;
  // ... handler logic
};

🛡 Error Handling

The SDK includes comprehensive error handling:

try {
  // Process webhook request
  await agent.processRequest(webhookBody);
} catch (error) {
  if (error.message.includes('API_TOKEN')) {
    console.error('Invalid API token. Run: superdapp configure');
  } else {
    console.error('Request processing failed:', error);
  }
}

🔐 Security Best Practices

1. Never commit API tokens to version control
2. Use environment variables for sensitive configuration
3. Validate all user inputs before processing
4. Implement rate limiting for command handlers
5. Use HTTPS for all API communications

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• 📖 Documentation Hub - Complete SDK documentation
• 💬 Discord Community
• 🐛 Issue Tracker
• 📧 Email Support

Built with ❤️ by the SuperDapp Team