A modern, type-safe Python client for the VoIP.ms API with Pydantic validation, async support, and a rich CLI.

• 🚀 Complete API Coverage: All 217 VoIP.ms API methods dynamically generated from the official WSDL
• 🔍 Full Type Safety: Pydantic models with comprehensive type hints and validation
• ⚡ Async Support: Both sync and async clients for optimal performance
• 🎨 Rich CLI: Beautiful command-line interface with auto-completion and formatted output
• 🔄 Cross-Reference Decoding: Automatic translation of numeric codes to human-readable values
• 📝 Smart Validation: Automatic type coercion, date parsing, and constraint validation
• 🤖 Smart Defaults: Intelligent parameter defaults (timezone, date ranges, etc.)
• 🔧 IDE Friendly: Generated .pyi stubs for perfect auto-completion
• 📊 Data-Driven: Two-stage API definition - source from WSDL/HTML, runtime with corrections

pip install voipms

Or install from source:

git clone https://github.com/your-username/voipms.git
cd voipms
pip install -e .

1. Set your credentials:

# Get your API credentials from https://voip.ms/m/api.php
export VOIPMS_USERNAME='[email protected]'
export VOIPMS_API_PASSWORD='your-api-password'

2. Use the client:

from voipms import VoIPMSClient

# Create client (credentials from environment)
client = VoIPMSClient()

# Get account balance
balance = client.getBalance()
print(f"Balance: ${balance['balance']['current_balance']}")

# Get CDR (with automatic date range)
cdr = client.getCDR(answered=True)
print(f"Found {len(cdr['cdr'])} calls")

3. Async example:

from voipms import VoIPMSAsyncClient
import asyncio

async def main():
    async with VoIPMSAsyncClient() as client:
        balance = await client.getBalance()
        print(f"Balance: ${balance['balance']['current_balance']}")

asyncio.run(main())

4. CLI usage:

# After installation
voipms getBalance
voipms getServersInfo
voipms getCDR --date_from="7 days ago" --date_to="today"

# Use the new decode feature for human-readable output
voipms --decode getSubAccounts --account="100001_mydomain"

# Get help
voipms --help
voipms list-methods
voipms help getCDR

The CLI can automatically decode numeric codes to human-readable values:

# Without decode - shows numeric codes
voipms getSubAccounts --account="100001_mydomain"
# Output: "auth_type": "1", "device_type": "2", ...

# With decode - shows human-readable values
voipms --decode getSubAccounts --account="100001_mydomain"
# Output: "auth_type": "1", "auth_type_decoded": "User/Password Authentication",
#         "device_type": "2", "device_type_decoded": "ATA device, IP Phone or Softphone", ...

The decoder:

• Automatically identifies fields with cross-references (127 fields across the API)
• Makes parallel API calls to fetch lookup values (2.5x faster than serial)
• Caches results within a single CLI execution
• Adds _decoded fields without modifying original values

The client properly validates string parameters that represent numeric values:

# These all work correctly:
client.setDIDInfo(did="5551234567", callerid_prefix="1")  # Valid: "1" is numeric
client.setDIDInfo(did="5551234567", callerid_prefix=1)    # Also valid: converts to "1"

# This raises ValidationError:
client.setDIDInfo(did="5551234567", callerid_prefix="abc")  # Invalid: not numeric

The client uses dateparser for flexible date inputs:

# All of these work:
client.getCDR(date_from="2025-01-01", date_to="2025-01-31")
client.getCDR(date_from="yesterday", date_to="today")
client.getCDR(date_from="1 week ago", date_to="now")

Every method has full type hints with detailed parameter information:

# Your IDE will show:
def getCDR(
    self,
    date_from: Annotated[str, Field(description="Start date for CDR retrieval")],
    date_to: Annotated[str, Field(description="End date for CDR retrieval")],
    answered: Annotated[Literal["0", "1"], Field(description="Include answered calls")] = None,
    # ... all parameters with descriptions and constraints
) -> Dict[str, Any]:

voipms/
├── src/voipms/          # Main package
│   ├── __init__.py
│   ├── base_client.py   # Base client with shared functionality
│   ├── client.py        # Synchronous client implementation
│   ├── async_client.py  # Asynchronous client implementation
│   ├── method_factory.py # Dynamic method generation
│   ├── validation.py    # Pydantic model factory
│   ├── type_validators.py # Type validators and converters
│   ├── cli.py           # Rich CLI interface
│   ├── cli_decoder.py   # Cross-reference decoder for CLI
│   ├── api_definition.json    # Complete API metadata
│   ├── cli_smart_defaults.json # CLI smart defaults
│   └── *.pyi            # Generated type stubs
├── resources/           # Source files for API definition
│   ├── server.wsdl      # VoIP.ms WSDL file
│   └── voipms_api_documentation.html  # HTML docs
├── tools/               # API definition generation tools
│   ├── cli.py           # Unified tools CLI
│   ├── commands/        # CLI command implementations
│   ├── parsers/         # WSDL and HTML parsers
│   ├── config/          # Tool configurations
│   ├── generate_api_definition.py
│   ├── generate_type_stubs.py
│   └── download_api_docs.py
├── examples/            # Example scripts
│   ├── basic_usage.py
│   ├── async_usage.py
│   └── backup_account_complete.py
└── tests/              # Test suite

## Regenerating the API Definitions

### Quick Regeneration

To regenerate all API definitions and type stubs:

```bash
# Regenerate everything (recommended)
uv run tools/cli.py generate

This runs three stages automatically:

1. Source Generation: Creates tools/generated/api_definition_source.json from WSDL/HTML
2. Quirks Application: Creates api_definition.json with runtime adjustments
3. Type Stubs: Updates .pyi files for IDE support

Regenerate the API definitions when:

1. VoIP.ms Updates Their API:

   # First, update HTML documentation
   cp /path/to/voipms_api_documentation.html resources/
   
   # Then regenerate
   uv run tools/cli.py generate

2. You Add New Corrections:

   # Edit tools/config/api_corrections.json
   # Then regenerate (only stages 2-3 needed)
   uv run tools/cli.py generate --stage=quirks
   uv run tools/cli.py generate --stage=stubs

3. You Update Type Overrides:

   # Edit tools/config/api_corrections.json
   # Then regenerate everything
   uv run tools/cli.py generate

# Stage 1: Generate source definition from WSDL/HTML
uv run tools/cli.py generate --stage=source

# Stage 2: Apply quirks to source definition
uv run tools/cli.py generate --stage=quirks

# Stage 3: Generate Python type stubs
uv run tools/cli.py generate --stage=stubs

The system uses a two-stage approach:

The client loads api_definition.json at runtime, which includes all quirks and adjustments.

This project uses uv for dependency management:

# Install dependencies
uv sync

# Run tests
uv run pytest

# Run linting
uv run ruff check .
uv run mypy src/

Contributions are welcome! Please feel free to submit a Pull Request.

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

This is an independent project and is not affiliated with or endorsed by VoIP.ms.