Package Exports

@relay-works/sms-dev
@relay-works/sms-dev/dist/cli.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@relay-works/sms-dev) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

📱 sms-dev

Local SMS development environment - the Mailtrap for SMS

Test SMS applications without costs, phone numbers, or external dependencies. A complete local development tool that simulates SMS functionality with a beautiful web interface.

✨ Features

🚀 Zero Setup - Works instantly without configuration
📱 Virtual Phone UI - Beautiful dark mode interface for testing
🔄 Real-time Updates - WebSocket connections for live message flow
🪝 Webhook Testing - Forward messages to your application
🔍 Message Search - Find conversations and messages instantly
📊 Performance Testing - Load testing with configurable parameters
🤖 Conversation Flows - Automated message sequences with conditions
📤 Export Data - Export conversations as JSON or CSV
⚙️ Flexible Config - File, environment, or CLI configuration
🎨 Developer First - Designed for modern development workflows

🚀 Quick Start

Global Installation

# Install globally via npm
npm install -g @relay-works/sms-dev

# Start the development environment
sms-dev start

# Open in browser
# API: http://localhost:4001
# UI: http://localhost:4000

Local Installation

# Install locally in your project
npm install --save-dev @relay-works/sms-dev

# Add to package.json scripts
{
  "scripts": {
    "sms-dev": "sms-dev start"
  }
}

# Run in your project
npm run sms-dev

📖 Usage Examples

Basic SMS Testing

// Your application code - raw message
const response = await fetch('http://localhost:4001/v1/messages', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    to: '+1234567890',
    body: 'Hello from my app!'
  })
})

const message = await response.json()
console.log('Message sent:', message.id)
console.log('Message text:', message.message)

Template-Based SMS (Production-Compatible)

// Using templates (required for Relay Starter tier in production)
const response = await fetch('http://localhost:4001/v1/messages/send-template', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    template: 'otp-verification',
    to: '+1234567890',
    data: {
      code: '123456',
      expiry: '10'
    }
  })
})

const message = await response.json()
console.log('Template sent:', message.id)
console.log('Rendered text:', message.message)
// Output: "Your verification code is 123456. It expires in 10 minutes."

Webhook Testing

# Start with webhook forwarding
sms-dev start --webhook-url http://localhost:3000/webhook/sms

# Your app will receive webhooks for all messages

Configuration File

// sms-dev.config.js
module.exports = {
  apiPort: 4001,
  uiPort: 4000,
  webhookUrl: 'http://localhost:3000/webhook/sms',
  cors: {
    enabled: true,
    origins: ['http://localhost:3000']
  }
}

🛠️ CLI Commands

Core Commands

sms-dev start              # Start API and UI servers
sms-dev start --no-ui      # Start API only
sms-dev stop               # Stop all servers
sms-dev status             # Check server status
sms-dev config             # Show current configuration

Configuration

sms-dev init               # Generate config file
sms-dev init --json        # Generate JSON config
sms-dev config --config custom.js  # Use custom config

Testing Utilities

# Mock phone management
sms-dev mock-phone create --phone +1234567890 --name "Test User"
sms-dev mock-phone list
sms-dev mock-phone delete --phone +1234567890

# Conversation flows
sms-dev flow create --name "Welcome Flow"
sms-dev flow list
sms-dev flow execute --flow-id flow_123 --phone +1234567890

# Data export
sms-dev export messages --format json --output messages.json
sms-dev export conversations --format csv

# Performance testing
sms-dev perf stats
sms-dev perf load-test --messages 1000 --users 10 --duration 60

🔧 Configuration Options

CLI Options

sms-dev start [options]

Options:
  -p, --port <port>         API server port (default: 4001)
  --ui-port <port>          UI server port (default: 4000)
  -w, --webhook-url <url>   Webhook URL for forwarding
  --cors-origins <origins>  CORS allowed origins
  --no-ui                   Disable UI server
  -v, --verbose             Enable verbose logging
  -c, --config <file>       Configuration file path

Environment Variables

SMS_DEV_API_PORT=4001         # API server port
SMS_DEV_UI_PORT=4000          # UI server port
SMS_DEV_WEBHOOK_URL=...       # Webhook URL
SMS_DEV_CORS_ORIGINS=...      # CORS origins (comma-separated)
SMS_DEV_VERBOSE=true          # Enable verbose logging
SMS_DEV_NO_UI=true            # Disable UI server

Configuration File

// sms-dev.config.js
module.exports = {
  // Server configuration
  apiPort: 4001,
  uiPort: 4000,
  
  // Webhook testing
  webhookUrl: 'http://localhost:3000/webhook/sms',
  
  // CORS configuration
  cors: {
    enabled: true,
    origins: ['*'] // Allow all origins in development
  },
  
  // Logging
  logging: {
    enabled: true,
    level: 'info' // 'debug' | 'info' | 'warn' | 'error'
  }
}

🔌 API Documentation

Send Message (Raw)

POST /v1/messages
Content-Type: application/json

{
  "to": "+1234567890",
  "from": "+15551234567",
  "body": "Hello world!"
}

Send Template Message (Production-Compatible)

POST /v1/messages/send-template
Content-Type: application/json

{
  "template": "otp-verification",
  "to": "+1234567890",
  "data": {
    "code": "123456",
    "expiry": "10"
  }
}

List Available Templates

GET /v1/messages/templates

Response includes mock templates:

otp-verification - 2FA verification codes
password-reset - Password reset codes
appointment-reminder - Appointment notifications
order-confirmation - Order confirmations
shipping-update - Shipping notifications

List Messages

GET /v1/messages?limit=20&offset=0&search=hello&status=delivered

Export Messages

GET /v1/messages/export?format=json&phone=1234567890&from_date=2024-01-01

Performance Stats

GET /v1/dev/performance/stats

View Full API Documentation →

Production Note: In production Relay API, Starter tier users ($19/mo) must use templates - raw message sending returns a 402 error. SMS-Dev allows both for testing flexibility. Learn about production differences →

🎯 Framework Integration

Express.js

import express from 'express'

const app = express()

// Webhook endpoint for sms-dev
app.post('/webhook/sms', express.json(), (req, res) => {
  const { id, to, from, body, status } = req.body
  console.log('SMS received:', { id, to, from, body, status })
  
  // Process your SMS logic here
  
  res.json({ success: true })
})

app.listen(3000)

// Start sms-dev with webhook
// sms-dev start --webhook-url http://localhost:3000/webhook/sms

Next.js

// pages/api/webhook/sms.js
export default function handler(req, res) {
  if (req.method === 'POST') {
    const { id, to, from, body, status } = req.body
    console.log('SMS received:', { id, to, from, body, status })
    
    // Process your SMS logic here
    
    res.status(200).json({ success: true })
  } else {
    res.setHeader('Allow', ['POST'])
    res.status(405).end(`Method ${req.method} Not Allowed`)
  }
}

React Testing

// hooks/useSMSTesting.js
import { useState } from 'react'

export function useSMSTesting() {
  const [messages, setMessages] = useState([])
  
  const sendTestMessage = async (to, body) => {
    const response = await fetch('http://localhost:4001/v1/messages', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ to, body })
    })
    
    const message = await response.json()
    setMessages(prev => [...prev, message])
    return message
  }
  
  return { messages, sendTestMessage }
}

🔍 Troubleshooting

Port Already in Use

# Check what's using the port
lsof -i :4001

# Use different ports
sms-dev start --port 4002 --ui-port 4003

Permission Issues

# Install with correct permissions
sudo npm install -g @relay-works/sms-dev

# Or use npx without global install
npx @relay-works/sms-dev start

Configuration Issues

# Debug configuration
sms-dev config
sms-dev start --show-config

# Reset configuration
rm sms-dev.config.js
sms-dev init

📦 Monorepo Development

If you're working with the sms-dev source code:

# Clone repository
git clone https://github.com/pcdkd/smsdev.git
cd smsdev

# Install dependencies
npm install

# Build packages
npm run build

# Run local development
./apps/sms-dev/dist/cli.js start

🤝 Contributing

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

Development Setup

# Fork and clone the repository
git clone https://github.com/your-username/smsdev.git
cd smsdev

# Install dependencies
npm install

# Build all packages
npm run build

# Run tests
npm test

# Start development server
npm run dev

📄 License

MIT © Relay

🔗 Links

Documentation: smsdev.app
GitHub: github.com/pcdkd/smsdev
npm: npmjs.com/package/@relay-works/sms-dev
Relay Platform: relay.works

Made with ❤️ by the Relay team

# Test automation - Sun Jun 30 11:08:30 EDT 2025