send-sms 0.1.0

# send-sms CLI

Modern command-line interface for sending SMS via FreeMobile API, using the `freemobile-api` library.

## Overview

This crate provides a comprehensive and intuitive CLI tool for SMS sending. It builds upon the `freemobile-api` crate for all API operations and focuses on command-line user experience.

## Features

- **Flexible input modes**: direct arguments, file, stdin, or interactive
- **Automatic stdin detection**: recognition of pipes and redirections
- **Flexible configuration**: environment variables, .env files, or CLI arguments
- **Interactive mode**: user-friendly interface with informative prompts
- **Robust error handling**: clear error messages and appropriate exit codes
- **Graceful interruption**: Ctrl+C support with clean shutdown
- **Verbose interface**: detailed mode for debugging and monitoring
- **Optimized binary**: 2.4MB size with maximum performance

## Installation

From the parent workspace:

```bash
cargo build --release
cargo install --path .
```

## Usage

### Basic syntax

```bash
send-sms [OPTIONS]

Options:
    -u, --user <USER_ID>        FreeMobile user ID (8 digits)
    -p, --pass <API_KEY>        FreeMobile API key  
    -m, --message <TEXT>        Message to send
    -f, --file <PATH>           Read message from file
    -v, --verbose               Verbose output
    -h, --help                  Print help
    -V, --version               Print version
```

### Usage examples

```bash
# Direct message
send-sms -m "Hello from Rust!"

# From a file
send-sms -f message.txt

# From stdin (automatic detection)
echo "Hello World" | send-sms
send-sms < message.txt

# Interactive mode (default)
send-sms

# Verbose mode for debugging
send-sms -m "Test message" -v
```

## Configuration

The CLI supports multiple configuration methods (in order of priority):

1. **CLI Arguments**: `-u` and `-p`
2. **Environment Variables**: `FREEMOBILE_USER` and `FREEMOBILE_PASS`
3. **.env File**: in the working directory
4. **Interactive Prompts**: Asked automatically when credentials are missing

### Environment Variables

```bash
export FREEMOBILE_USER="12345678"
export FREEMOBILE_PASS="your-api-key"
```

### .env File

```env
FREEMOBILE_USER=12345678
FREEMOBILE_PASS=your-api-key
```

### Interactive Mode

When credentials are not provided via CLI arguments or environment variables, the CLI will prompt you interactively:

```bash
send-sms -m "Hello world"
# FreeMobile User ID: [you type your 8-digit user ID]
# FreeMobile API Key: [you type your API key, hidden, no confirmation needed]
```

This makes the CLI user-friendly for first-time users or when testing.

## Architecture

### Modules

- **`config`**: CLI configuration management with validation
- **`input`**: Management of different input sources (file, stdin, interactive)
- **`main`**: Main entry point with operation orchestration

### Dependencies

- **`freemobile-api`**: API library (local crate)
- **`clap`**: CLI argument parsing with validation
- **`inquire`**: Interactive user interface
- **`tokio`**: Async runtime for performance
- **`dotenv`**: .env file support

## Error Handling

The CLI provides clear error messages for all use cases:

- **Missing credentials**: Instructions to configure `FREEMOBILE_USER` and `FREEMOBILE_PASS`
- **Invalid user ID**: Must be exactly 8 digits
- **Empty message**: Cannot be empty or contain only spaces
- **File not found**: Invalid file path
- **API errors**: Clear error messages from the `freemobile-api` library

All error messages include action suggestions to resolve the problem.

## Integration

### Scripts and automation

```bash
#!/bin/bash
# Deployment notification script
if deploy_app; then
    send-sms -m "✅ Deployment successful at $(date)"
else
    send-sms -m "❌ Deployment failed at $(date)"
fi
```

### System monitoring

```bash
# High CPU alert
cpu_usage=$(top -l 1 | grep "CPU usage" | awk '{print $3}' | sed 's/%//')
if (( $(echo "$cpu_usage > 90" | bc -l) )); then
    send-sms -m "⚠️ Critical CPU usage: ${cpu_usage}%"
fi
```

### CI/CD Pipeline

```bash
# Build notification
make build && \
  send-sms -m "✅ Build successful for commit $(git rev-parse --short HEAD)" || \
  send-sms -m "❌ Build failed for commit $(git rev-parse --short HEAD)"
```

## Development

### Tests

```bash
# Unit tests
cargo test -p send-sms-cli

# Tests with detailed output
cargo test -p send-sms-cli -- --nocapture

# Test specific module
cargo test -p send-sms-cli config::tests
```

### Debugging

Use verbose mode (`-v`) to see execution details:

```bash
send-sms -v -m "Test message"
# Shows:
# 🚀 Starting send-sms v0.1.0
# 📱 User ID: 1234****
# 📄 Message preview: ...
# 📤 Sending SMS...
# ✅ SMS sent successfully!
```

For advanced debugging (shows original message when emoji sanitization occurs):

```bash
DEBUG=1 send-sms -v -m "Hello 😀 world!"
# Shows:
# 🐛 DEBUG - Original message: Hello 😀 world!
# 🐛 DEBUG - Sanitized message (what will be sent):
# 📄 Message preview: Hello [] world!
```