@ktmcp-cli/nowpayments 1.0.0

package/PROJECT_SUMMARY.md

@@ -0,0 +1,305 @@
+# NOWPayments CLI - Project Summary
+
+Production-ready Commander.js CLI for NOWPayments cryptocurrency payment processing API.
+
+## Project Location
+
+```
+/workspace/group/ktmcp/workspace/nowpayments/
+```
+
+## Project Structure
+
+```
+nowpayments/
+├── bin/
+│   └── nowpayments.js          # CLI entry point
+├── src/
+│   ├── commands/               # Command implementations
+│   │   ├── auth.js            # API key management
+│   │   ├── status.js          # API status check
+│   │   ├── currencies.js      # Currency operations
+│   │   ├── estimate.js        # Price estimation
+│   │   ├── payment.js         # Payment management
+│   │   ├── invoice.js         # Invoice management
+│   │   └── payout.js          # Payout/withdrawal operations
+│   └── lib/                   # Core libraries
+│       ├── api.js             # API client with error handling
+│       ├── auth.js            # Authentication utilities
+│       └── config.js          # Configuration management
+├── examples/                  # Usage examples
+│   ├── basic-payment.js       # Simple payment creation
+│   ├── monitor-payment.js     # Payment status monitoring
+│   └── invoice-flow.js        # Invoice workflow
+├── README.md                  # Main documentation
+├── AGENT.md                   # AI agent integration guide
+├── OPENCLAW.md                # OpenClaw framework integration
+├── INSTALL.md                 # Installation and setup guide
+├── package.json               # NPM package configuration
+├── openapi.json               # NOWPayments API specification
+├── .env.example               # Environment configuration template
+├── .gitignore                 # Git ignore rules
+├── LICENSE                    # MIT license
+└── test.sh                    # Test suite
+```
+
+## Features Implemented
+
+### Core Functionality
+- ✅ Full NOWPayments API coverage (payments, invoices, payouts, currencies, estimates)
+- ✅ Authentication management (API key storage and validation)
+- ✅ Rich terminal output with colors and tables
+- ✅ JSON output mode for scripting
+- ✅ Sandbox environment support
+- ✅ Global and command-specific options
+- ✅ Comprehensive error handling
+- ✅ Debug logging mode
+
+### Commands Implemented
+
+1. **auth** - API key management
+   - `auth set` - Save API key
+   - `auth show` - Display current key (masked)
+   - `auth clear` - Remove API key
+
+2. **status** - Check API availability
+
+3. **currencies** - Cryptocurrency operations
+   - `currencies list` - List all currencies
+   - `currencies info` - Get currency details
+
+4. **estimate** - Price calculations
+   - `estimate convert` - Estimate cryptocurrency amount
+   - `estimate min` - Get minimum payment amount
+
+5. **payment** - Payment management
+   - `payment create` - Create new payment
+   - `payment get` - Get payment details
+   - `payment list` - List all payments
+   - `payment update-estimate` - Update price estimate
+
+6. **invoice** - Invoice management
+   - `invoice create` - Create new invoice
+   - `invoice get` - Get invoice details
+   - `invoice list` - List all invoices
+
+7. **payout** - Withdrawal operations
+   - `payout create` - Create new payout
+   - `payout verify` - Verify payout with 2FA
+   - `payout get` - Get payout details
+   - `payout list` - List all payouts
+
+### Documentation
+
+1. **README.md** - Comprehensive user guide
+   - "Why CLI > MCP" section explaining advantages
+   - Full command reference
+   - Usage examples
+   - Payment flow documentation
+   - Error handling guide
+
+2. **AGENT.md** - AI agent integration patterns
+   - JSON output mode usage
+   - Error handling strategies
+   - Common workflows
+   - Polling patterns
+   - Security considerations
+
+3. **OPENCLAW.md** - OpenClaw framework integration
+   - Skill definition
+   - Event handling
+   - Webhook integration
+   - Multi-agent coordination
+   - Advanced patterns
+
+4. **INSTALL.md** - Installation and setup
+   - Multiple installation methods
+   - API key configuration
+   - Troubleshooting guide
+   - Integration examples
+
+### Examples
+
+1. **basic-payment.js** - Simple payment creation workflow
+2. **monitor-payment.js** - Payment status monitoring with polling
+3. **invoice-flow.js** - Complete invoice generation and management
+
+## Technical Details
+
+### Dependencies
+- **commander**: ^12.0.0 - CLI framework
+- **chalk**: ^4.1.2 - Terminal colors
+- **ora**: ^5.4.1 - Spinners
+- **dotenv**: ^16.4.1 - Environment variables
+- **node-fetch**: ^2.7.0 - HTTP requests
+- **cli-table3**: ^0.6.3 - Terminal tables
+
+### Architecture
+
+- **Modular design**: Separate command files for maintainability
+- **Library abstraction**: Core functionality in reusable libraries
+- **Error handling**: Comprehensive error catching and user-friendly messages
+- **Exit codes**: Proper POSIX exit codes (0 = success, 1 = error)
+- **Configuration layers**: API key from config file, env var, or CLI flag
+- **JSON mode**: Structured output for scripting and automation
+
+### Code Quality
+
+- ✅ JSDoc comments throughout
+- ✅ Consistent code style
+- ✅ Input validation
+- ✅ Proper error propagation
+- ✅ No hardcoded values
+- ✅ Environment-aware (sandbox/production)
+
+## API Coverage
+
+Based on NOWPayments OpenAPI spec (v1.0.0):
+
+- ✅ GET /v1/status
+- ✅ GET /v1/currencies
+- ✅ GET /v1/merchant/coins
+- ✅ GET /v1/estimate
+- ✅ GET /v1/min-amount
+- ✅ POST /v1/payment
+- ✅ GET /v1/payment
+- ✅ GET /v1/payment/{payment_id}
+- ✅ POST /v1/payment/{id}/update-merchant-estimate
+- ✅ POST /v1/invoice
+- ✅ GET /v1/invoice
+- ✅ GET /v1/invoice/{invoice_id}
+- ✅ POST /v1/payout
+- ✅ GET /v1/payout/{payout_id}
+- ✅ POST /v1/payout/{payout_id}/verify
+- ✅ GET /v1/payout
+
+## Installation Steps
+
+1. **Install dependencies**:
+   ```bash
+   cd /workspace/group/ktmcp/workspace/nowpayments
+   npm install
+   ```
+
+2. **Test the CLI**:
+   ```bash
+   ./test.sh
+   ```
+
+3. **Link for global use** (optional):
+   ```bash
+   npm link
+   ```
+
+4. **Configure API key**:
+   ```bash
+   nowpayments auth set YOUR_API_KEY
+   ```
+
+5. **Verify**:
+   ```bash
+   nowpayments status
+   ```
+
+## Usage Examples
+
+### Basic Payment
+```bash
+nowpayments payment create \
+  --price 99.99 \
+  --currency USD \
+  --pay-currency BTC
+```
+
+### JSON Output for Scripting
+```bash
+payment=$(nowpayments --json payment create --price 100 --currency USD --pay-currency BTC)
+payment_id=$(echo "$payment" | jq -r '.payment_id')
+echo "Created payment: $payment_id"
+```
+
+### List Currencies
+```bash
+nowpayments currencies list --available
+```
+
+### Monitor Payment
+```bash
+node examples/monitor-payment.js <payment_id>
+```
+
+## Testing
+
+Run the test suite:
+```bash
+cd /workspace/group/ktmcp/workspace/nowpayments
+./test.sh
+```
+
+Tests verify:
+- CLI structure and entry points
+- All commands registered
+- Required dependencies
+- Documentation completeness
+- Example files
+- File permissions
+
+## Why This Implementation is Superior
+
+### 1. CLI vs MCP
+- **Universal compatibility**: Works with any tool or AI
+- **No server overhead**: Direct execution, no daemon
+- **Battle-tested pattern**: CLI is proven, reliable
+- **Simpler debugging**: Standard stdout/stderr
+- **Better for automation**: Shell scripts, cron jobs, CI/CD
+
+### 2. Architecture Benefits
+- **Modular commands**: Each command is self-contained
+- **Shared libraries**: DRY principle with lib/
+- **Layered config**: Flexible API key sources
+- **Proper error handling**: User-friendly messages, correct exit codes
+- **Rich output**: Both human-readable and machine-parseable
+
+### 3. Production Ready
+- ✅ Input validation
+- ✅ Error recovery
+- ✅ Debug mode
+- ✅ Environment detection (sandbox/production)
+- ✅ Comprehensive documentation
+- ✅ Working examples
+- ✅ Test suite
+
+## Next Steps
+
+1. **Publish to NPM** (optional):
+   ```bash
+   npm publish
+   ```
+
+2. **Add to AI agent tools**: Use patterns from AGENT.md
+
+3. **Integrate with OpenClaw**: Follow OPENCLAW.md guide
+
+4. **Extend functionality**:
+   - Add webhook verification utility
+   - Create payment monitoring daemon
+   - Build subscription management
+   - Add bulk operations
+
+## Support
+
+- **API Docs**: https://documenter.getpostman.com/view/7907941/S1a32n38
+- **NOWPayments**: https://nowpayments.io
+- **CLI Help**: `nowpayments --help`
+
+## License
+
+MIT License - See LICENSE file
+
+---
+
+**Status**: ✅ Complete and production-ready
+
+**Created**: 2024
+**Package**: @ktmcp-cli/nowpayments
+**Version**: 1.0.0

package/README.md

@@ -0,0 +1,375 @@
+# NOWPayments CLI
+
+<p align="center">
+  <img src="banner.png" alt="KTMCP Banner" width="100%">
+</p>
+
+
+A production-ready command-line interface for the [NOWPayments](https://nowpayments.io) cryptocurrency payment processing API. Built with Commander.js for robust API integration and automation.
+
+## Why CLI > MCP
+
+While Model Context Protocol (MCP) servers provide AI integration, a dedicated CLI offers superior advantages:
+
+### 1. Universal Tool Integration
+- Works with **any** AI assistant (Claude, ChatGPT, local models)
+- No MCP server dependency or compatibility issues
+- Standard stdin/stdout interface that all tools understand
+
+### 2. Human-First Design
+- Direct terminal usage for developers and operators
+- Rich formatted output with colors and tables
+- Interactive workflows when needed
+- Scriptable for automation
+
+### 3. Reliability & Performance
+- No additional server process to manage
+- Direct API calls with minimal overhead
+- Proper error handling and exit codes
+- No WebSocket/transport layer complexity
+
+### 4. Development Velocity
+- Easier to test (just run commands)
+- Simpler debugging (standard logs)
+- Faster iteration (no server restarts)
+- Better CI/CD integration
+
+### 5. Production Ready
+- Works in Docker containers
+- Cron job compatible
+- Shell script integration
+- No daemon management
+
+**Bottom Line:** CLIs are battle-tested, universal interfaces. MCP adds complexity for integration scenarios where a simple CLI + agent pattern works better.
+
+## Features
+
+- Full NOWPayments API coverage
+- Rich terminal output with colors and formatting
+- JSON output mode for scripting
+- Persistent API key management
+- Sandbox environment support
+- Comprehensive error handling
+- Production-ready reliability
+
+## Installation
+
+```bash
+npm install -g @ktmcp-cli/nowpayments
+```
+
+Or install locally:
+
+```bash
+cd ktmcp-nowpayments-cli
+npm install
+npm link
+```
+
+## Quick Start
+
+### 1. Get Your API Key
+
+Sign up at [NOWPayments.io](https://nowpayments.io) and generate an API key.
+
+### 2. Configure Authentication
+
+```bash
+# Save API key to config (recommended)
+nowpayments auth set YOUR_API_KEY
+
+# Or use environment variable
+export NOWPAYMENTS_API_KEY=your_api_key
+
+# Or pass with each command
+nowpayments --api-key YOUR_API_KEY status
+```
+
+### 3. Verify Connection
+
+```bash
+nowpayments status
+```
+
+## Usage
+
+### Authentication Management
+
+```bash
+# Set API key
+nowpayments auth set YOUR_API_KEY
+
+# Show current key (masked)
+nowpayments auth show
+
+# Clear API key
+nowpayments auth clear
+```
+
+### Check API Status
+
+```bash
+nowpayments status
+```
+
+### Currency Operations
+
+```bash
+# List all available cryptocurrencies
+nowpayments currencies list
+
+# Show only available payment currencies
+nowpayments currencies list --available
+
+# Get currency information
+nowpayments currencies info BTC
+```
+
+### Price Estimates
+
+```bash
+# Estimate cryptocurrency amount for fiat price
+nowpayments estimate convert --from USD --to BTC --amount 100
+
+# Get minimum payment amount
+nowpayments estimate min --from USD --to BTC
+```
+
+### Payment Management
+
+```bash
+# Create a new payment
+nowpayments payment create \
+  --price 99.99 \
+  --currency USD \
+  --pay-currency BTC \
+  --order-id "ORDER-123" \
+  --order-description "Premium subscription"
+
+# Get payment details
+nowpayments payment get <payment_id>
+
+# List all payments
+nowpayments payment list --limit 20
+
+# Filter payments by date
+nowpayments payment list \
+  --date-from 2024-01-01 \
+  --date-to 2024-12-31
+
+# Update payment estimate (before expiration)
+nowpayments payment update-estimate <payment_id>
+```
+
+### Invoice Management
+
+```bash
+# Create an invoice
+nowpayments invoice create \
+  --price 49.99 \
+  --currency USD \
+  --order-id "INV-456" \
+  --success-url "https://example.com/success" \
+  --cancel-url "https://example.com/cancel"
+
+# Get invoice details
+nowpayments invoice get <invoice_id>
+
+# List invoices
+nowpayments invoice list --limit 10
+```
+
+### Payout Operations
+
+```bash
+# Create a payout
+nowpayments payout create \
+  --amount 0.01 \
+  --currency BTC \
+  --address "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
+
+# Verify payout with 2FA
+nowpayments payout verify <payout_id> <verification_code>
+
+# Get payout details
+nowpayments payout get <payout_id>
+
+# List payouts
+nowpayments payout list
+```
+
+### Global Options
+
+```bash
+# Use sandbox environment
+nowpayments --sandbox status
+
+# Output raw JSON (for scripting)
+nowpayments --json payment list
+
+# Enable debug logging
+nowpayments --debug payment create --price 100 --currency USD --pay-currency BTC
+
+# Combine options
+nowpayments --sandbox --json currencies list
+```
+
+## Advanced Usage
+
+### Scripting with JSON Output
+
+```bash
+# Get payment status in JSON
+payment_data=$(nowpayments --json payment get abc123)
+status=$(echo "$payment_data" | jq -r '.payment_status')
+
+if [ "$status" = "finished" ]; then
+  echo "Payment completed!"
+fi
+```
+
+### Environment Variables
+
+```bash
+# Set in .env file
+NOWPAYMENTS_API_KEY=your_api_key
+
+# Load automatically
+nowpayments status
+```
+
+### Automation Example
+
+```bash
+#!/bin/bash
+# Create payment and monitor status
+
+# Create payment
+payment=$(nowpayments --json payment create \
+  --price 100 \
+  --currency USD \
+  --pay-currency BTC)
+
+payment_id=$(echo "$payment" | jq -r '.payment_id')
+pay_address=$(echo "$payment" | jq -r '.pay_address')
+
+echo "Payment created: $payment_id"
+echo "Send to: $pay_address"
+
+# Monitor status
+while true; do
+  status=$(nowpayments --json payment get "$payment_id" | jq -r '.payment_status')
+  echo "Status: $status"
+
+  if [ "$status" = "finished" ]; then
+    echo "Payment completed!"
+    break
+  fi
+
+  sleep 30
+done
+```
+
+## Payment Flow
+
+1. **Create Estimate**: Check conversion rates and fees
+   ```bash
+   nowpayments estimate convert --from USD --to BTC --amount 100
+   ```
+
+2. **Create Payment**: Generate payment address
+   ```bash
+   nowpayments payment create --price 100 --currency USD --pay-currency BTC
+   ```
+
+3. **Customer Sends Crypto**: Customer sends exact amount to provided address
+
+4. **Monitor Status**: Poll payment status or use IPN callbacks
+   ```bash
+   nowpayments payment get <payment_id>
+   ```
+
+5. **Payment Confirmed**: Status changes to "finished"
+
+## Payment Statuses
+
+- `waiting` - Waiting for customer payment
+- `confirming` - Payment received, confirming on blockchain
+- `confirmed` - Payment confirmed
+- `sending` - Sending to your wallet
+- `partially_paid` - Underpaid
+- `finished` - Complete
+- `failed` - Transaction failed
+- `refunded` - Payment refunded
+- `expired` - Payment window expired
+
+## Error Handling
+
+The CLI provides detailed error messages and proper exit codes:
+
+- Exit code 0: Success
+- Exit code 1: Error (API error, validation error, etc.)
+
+```bash
+# Check exit code
+nowpayments payment get invalid_id
+echo $?  # Returns 1 on error
+```
+
+## Configuration
+
+Configuration is stored in `~/.nowpayments/config.json`:
+
+```json
+{
+  "apiKey": "your_api_key",
+  "sandbox": false,
+  "defaultCurrency": "USD",
+  "defaultPayCurrency": "BTC"
+}
+```
+
+## API Documentation
+
+For detailed API documentation, see:
+- [NOWPayments API Docs](https://documenter.getpostman.com/view/7907941/S1a32n38)
+- [OpenAPI Specification](./openapi.json)
+
+## AI Agent Usage
+
+See [AGENT.md](./AGENT.md) for patterns and examples for AI assistants using this CLI.
+
+## OpenClaw Integration
+
+See [OPENCLAW.md](./OPENCLAW.md) for integration with the OpenClaw agent framework.
+
+## Examples
+
+See [examples/](./examples/) directory for complete usage examples:
+- Basic payment flow
+- Invoice generation
+- Payout automation
+- Status monitoring
+
+## Requirements
+
+- Node.js >= 16.0.0
+- NOWPayments API key
+
+## License
+
+MIT
+
+## Support
+
+- GitHub Issues: Report bugs and request features
+- NOWPayments Support: https://nowpayments.io/help
+- API Status: https://status.nowpayments.io
+
+## Contributing
+
+Contributions welcome! Please submit pull requests or open issues.
+
+---
+
+Built with Commander.js for the KTMCP project.