destinations-api

# Destinations API Plugin for Claude Code

A comprehensive Claude Code plugin providing access to global telecommunications data including mobile country codes (MCC), mobile network codes (MNC), E.164/E.212 mapping, carrier information, and billing increments for 200+ countries and 1000+ operators.

## Features

### 🔍 Slash Commands

- **`/destinations-api:destinations-search`** - Search telecom destinations by prefix, country, network, or MCC/MNC
- **`/destinations-api:billing-updates`** - Track billing increment changes and market trends
- **`/destinations-api:lookup-number`** - Identify carrier and billing info for specific phone numbers
- **`/destinations-api:compare-billing`** - Compare billing increments across countries and carriers

### 🤖 Specialized Agents

- **Telecom Routing Advisor** - Optimizes carrier routing based on cost and quality
- **Billing Trend Analyst** - Tracks billing changes and forecasts cost impacts
- **Fraud Detection Helper** - Validates numbers and detects suspicious patterns

### ⚡ Hooks

- API rate limit reminders (100 req/min)
- Response caching suggestions
- Phone number format validation

## Installation

### Quick Install (Recommended)

Add the GitHub marketplace and install the plugin:

```bash
# Add the marketplace from GitHub
/plugin marketplace add https://github.com/TelecomsXChangeAPi/destinations-api-claude-plugin.git

# Install the plugin
/plugin install destinations-api@destinations-api-marketplace

# Restart Claude Code to activate
```

The plugin will be immediately available with all slash commands and agents.

### Updating the Plugin

To get the latest version:

```bash
# Update marketplace metadata
/plugin marketplace update destinations-api-marketplace

# Reinstall to get updates
/plugin uninstall destinations-api@destinations-api-marketplace
/plugin install destinations-api@destinations-api-marketplace
```

### Local Development

For plugin development and testing:

```bash
# Clone the repository
git clone https://github.com/TelecomsXChangeAPi/destinations-api-claude-plugin.git
cd destinations-api-claude-plugin

# Create a development marketplace in parent directory
cd ..
mkdir dev-marketplace
cd dev-marketplace
mkdir .claude-plugin

# Create marketplace.json
cat > .claude-plugin/marketplace.json << 'EOF'
{
  "name": "dev-marketplace",
  "metadata": {
    "description": "Local development marketplace"
  },
  "owner": {"name": "Developer"},
  "plugins": [{
    "name": "destinations-api",
    "source": "../destinations-api-claude-plugin",
    "description": "Destinations API plugin (dev)"
  }]
}
EOF

# Start Claude Code from parent directory
cd ..
claude

# In Claude Code, add local marketplace
/plugin marketplace add ./dev-marketplace

# Install plugin
/plugin install destinations-api@dev-marketplace

# After making changes, reinstall:
/plugin uninstall destinations-api@dev-marketplace
/plugin install destinations-api@dev-marketplace
```

## Usage Examples

### Search for Destinations

```bash
# Search by country
/destinations-search Cambodia mobile networks

# Search by prefix
/destinations-search prefix +1212

# Search by MCC/MNC
/destinations-search mccmnc 45601
```

**Example output:**
```
┌───────────────────────────────────────────────────────────┐
│ Prefix  Country   Network          MCC/MNC  Billing      │
├───────────────────────────────────────────────────────────┤
│ 85510   CAMBODIA  Cellcard Mobile  45601    60/1  ★★★★  │
│ 85511   CAMBODIA  Smart Mobile     45606    60/60 ★★★   │
│ 85512   CAMBODIA  Metfone Mobile   45608    60/1  ★★★★  │
└───────────────────────────────────────────────────────────┘

Billing Legend:
• 60/1 = 60s minimum, then per-second (better)
• 60/60 = 60s minimum, then per-minute (standard)
```

### Track Billing Updates

```bash
# Recent updates (last 30 days)
/billing-updates recent

# Updates for specific year
/billing-updates 2025

# Improvements only
/billing-updates 2025 improved

# Specific country
/billing-updates Cambodia 2025
```

**Example output:**
```
BILLING UPDATES: Last 30 Days

Improvements: 12 | Deteriorations: 3

Recent Changes:
• 2025-10-01: CAMBODIA Cellcard - 60/60 → 60/1 (★★★★ Better!)
• 2025-09-28: THAILAND AIS - 60/60 → 1/1 (★★★★★ Much better!)
• 2025-09-25: VIETNAM Viettel - 30/1 → 1/1 (★★★★ Better!)

Cost Impact: Estimated 15-25% savings on affected routes
```

### Look Up Phone Numbers

```bash
# Lookup with international format
/lookup-number +855 12 345 6789

# Lookup with country code
/lookup-number 855123456789

# Lookup US number
/lookup-number +1-212-555-0100
```

**Example output:**
```
PHONE NUMBER ANALYSIS: +855 12 XXX XXXX

Country: CAMBODIA 🇰🇭
Prefix: 85512
Carrier: Metfone Mobile
Network Type: Mobile
MCC/MNC: 45608
Billing: 60/1 (60s minimum, then per-second)

Cost Estimate (per minute after minimum): $0.XX

Use Cases:
✓ Routing: Route via Metfone network
✓ Fraud Check: Valid Cambodia mobile number
✓ Cost Planning: Use 60/1 billing calculation
```

### Compare Billing Across Destinations

```bash
# Compare countries
/compare-billing Cambodia vs Thailand mobile

# Best billing in region
/compare-billing Southeast Asia mobile best billing

# Compare all carriers in country
/compare-billing United States mobile carriers
```

**Example output:**
```
BILLING COMPARISON: Southeast Asia Mobile

┌────────────────────────────────────────────────────────────┐
│ Country    Carrier    MCC/MNC  Billing  Rating  1min  5min│
├────────────────────────────────────────────────────────────┤
│ THAILAND   AIS        52001    1/1      ★★★★★  $0.XX $0.XX│
│ CAMBODIA   Cellcard   45601    60/1     ★★★★   $0.XX $0.XX│
│ VIETNAM    Viettel    45202    60/1     ★★★★   $0.XX $0.XX│
│ CAMBODIA   Smart      45606    60/60    ★★★    $0.XX $0.XX│
└────────────────────────────────────────────────────────────┘

RECOMMENDATION: Route Thailand traffic via AIS (1/1 billing)
SAVINGS: Up to 15% vs standard 60/60 billing
```

## Using Specialized Agents

### Telecom Routing Advisor

```bash
# Launch the agent
Please use the telecom routing advisor agent to analyze routing options for Cambodia mobile traffic

# The agent will:
- Query all available routes
- Compare billing structures
- Calculate cost scenarios
- Provide routing recommendations
```

### Billing Trend Analyst

```bash
# Launch the agent
Please use the billing trend analyst agent to analyze billing trends for Q4 2025

# The agent will:
- Track billing changes over time
- Identify improving/deteriorating markets
- Forecast cost impacts
- Recommend strategic actions
```

### Fraud Detection Helper

```bash
# Launch the agent
Please use the fraud detection helper agent to validate this phone number: +855123456789

# The agent will:
- Validate E.164 format
- Verify country/carrier match
- Check for suspicious patterns
- Assess fraud risk level
```

## API Information

The plugin uses the free Destinations API:
- **Base URL:** https://destinations-api.telecomsxchange.com
- **Rate Limit:** 100 requests per minute
- **Authentication:** None required (open access)
- **Response Format:** JSON

## Understanding Billing Increments

Billing increments are shown as `interval_1/interval_n`:

| Format | Meaning | Quality |
|--------|---------|---------|
| `1/1` | Per-second billing from start | ★★★★★ Best |
| `60/1` | 60s minimum, then per-second | ★★★★ Better |
| `30/30` | 30s increments throughout | ★★★ Good |
| `60/60` | Per-minute billing | ★★ Standard |
| `180/180` | 3-minute increments | ★ Less favorable |

**Lower initial intervals and smaller increments are better for cost control.**

## Common Use Cases

### 1. Telecom Routing Optimization
```bash
# Find best route for high-volume destination
/destinations-search United States mobile
/compare-billing US carriers by billing

# Use routing advisor for recommendations
Use the telecom routing advisor to optimize routing for US mobile traffic
```

### 2. Fraud Prevention
```bash
# Validate suspicious number
/lookup-number +855999999999

# Get fraud analysis
Use the fraud detection helper agent to analyze this CLI: +1234567890
```

### 3. Cost Forecasting
```bash
# Track billing changes
/billing-updates recent

# Analyze trends
Use the billing trend analyst to forecast Q1 2026 billing costs for our top 20 destinations
```

### 4. Mobile App Development
```bash
# Identify user's carrier from phone number
/lookup-number <user-phone-number>

# Validate international numbers
Use the fraud detection helper to validate user registration numbers
```

## Development

### Plugin Structure
```
destinations-api/
├── .claude-plugin/
│   └── plugin.json          # Plugin metadata
├── commands/                 # Slash commands
│   ├── destinations-search.md
│   ├── billing-updates.md
│   ├── lookup-number.md
│   └── compare-billing.md
├── agents/                   # Specialized agents
│   ├── telecom-routing-advisor.md
│   ├── billing-trend-analyst.md
│   └── fraud-detection-helper.md
├── hooks/                    # Event hooks
│   └── hooks.json
└── README.md
```

### Testing Changes

```bash
# Uninstall current version
/plugin uninstall destinations-api@dev-marketplace

# Reinstall after changes
/plugin install destinations-api@dev-marketplace

# Test commands
/help  # Verify commands appear
/destinations-search test
```

### Contributing

Contributions are welcome! Please see our [Contributing Guide](docs/CONTRIBUTING.md) for:
- Development setup and workflow
- Adding new commands and agents
- Testing guidelines
- Submitting pull requests

## Troubleshooting

### Commands Not Appearing
- Ensure plugin is installed: `/plugin`
- Restart Claude Code after installation
- Check `/help` for command list

### API Rate Limits
- Limit: 100 requests/minute
- Use pagination for large result sets
- Consider caching frequently accessed data

### No Results Found
- Verify country names are in UPPERCASE
- Check prefix format (digits only, no +)
- Try shorter prefixes for broader matches

## Documentation

For comprehensive documentation, see:

- **[Documentation Index](docs/README.md)** - Complete documentation hub
- **[API Reference](docs/API-REFERENCE.md)** - Detailed API endpoint documentation
- **[Usage Examples](docs/EXAMPLES.md)** - Real-world scenarios and tutorials
- **[Contributing Guide](docs/CONTRIBUTING.md)** - Plugin development and contribution workflow

## Support

- **API Documentation:** https://destinations-api.telecomsxchange.com/docs
- **OpenAPI Spec:** https://destinations-api.telecomsxchange.com/openapi.json
- **Issues:** [Report issues on GitHub](https://github.com/TelecomsXChangeAPi/destinations-api-claude-plugin/issues)
- **Proposals:** Submit data corrections via API's `/proposals/submit` endpoint

## License

MIT License - See [LICENSE](LICENSE) file for details

## Version History

### 1.0.0 (2025-10-09)
- Initial release
- 4 slash commands for API interaction
- 3 specialized agents for telecom analysis
- Event hooks for rate limiting and validation
- Comprehensive documentation and examples

---

**Made with ❤️ for the telecommunications community**