Initial commit

2026-04-27 22:21:51 +00:00
commit a11fa3b142
2 changed files with 293 additions and 0 deletions
@@ -0,0 +1,292 @@
+# VoIP.ms PHP Client and CLI
+
+This project provides a small PHP library and command-line tool for working
+with the VoIP.ms REST/JSON API.
+
+The goal is to make common VoIP.ms automation tasks easy from shell scripts,
+cron jobs, and PHP applications, while still allowing direct access to any raw
+API method when a command has not been wrapped yet.
+
+VoIP.ms API documentation:
+
+https://voip.ms/m/apidocs.php
+
+## What Is Included
+
+- `voipms-cli.php`: an executable CLI for calling VoIP.ms API methods.
+- `src/VoipMsClient.php`: a reusable PHP client class.
+- `src/VoipMsResponse.php`: a response wrapper for library callers.
+- `src/PhonebookGroupUpdateResult.php`: a result object for phonebook group
+  membership updates.
+- `src/PhonebookGroupEnsureResult.php`: a result object for finding or creating
+  phonebook groups.
+- `src/PhonebookNumberGroupResult.php`: a result object for idempotently adding
+  numbers to phonebook groups.
+- `docs/library.md`: PHP library usage examples.
+- `docs/mcp.md`: test MCP server usage and curl examples.
+- `bin/serve-mcp.sh`: launcher for a network-accessible test MCP server.
+- `mcp/http-server.php`: dependency-free HTTP JSON-RPC MCP endpoint.
+- `phonebook.php`: the original simple cURL example, intentionally left as a
+  reference.
+
+The CLI and library both talk to the same VoIP.ms endpoint:
+
+```text
+https://voip.ms/api/v1/rest.php
+```
+
+## Authentication
+
+The CLI reads credentials from environment variables:
+
+```bash
+export VOIPMS_API_USERNAME='you@example.com'
+export VOIPMS_API_PASSWORD='your-api-password'
+```
+
+Credentials can also be passed directly:
+
+```bash
+./voipms-cli.php getBalance --username you@example.com --password your-api-password
+```
+
+The endpoint can be overridden with `VOIPMS_API_ENDPOINT` or `--endpoint`.
+
+## CLI Overview
+
+The CLI can call any VoIP.ms API method:
+
+```bash
+./voipms-cli.php <method> key=value
+```
+
+Examples:
+
+```bash
+./voipms-cli.php getBalance
+./voipms-cli.php getDIDsInfo
+./voipms-cli.php getSMS date_from=2026-04-01 date_to=2026-04-20 did=5551234567
+./voipms-cli.php sendSMS did=5551234567 dst=5553334444 message="Hello"
+```
+
+Use `--dry-run` to see the method and parameters without making an API request:
+
+```bash
+./voipms-cli.php getPhonebook Spam --dry-run
+```
+
+Output format defaults to pretty JSON. Use `--format json` for compact JSON or
+`--format raw` for the raw API response.
+
+## Help And Discovery
+
+General help:
+
+```bash
+./voipms-cli.php help
+```
+
+Command help works in both directions:
+
+```bash
+./voipms-cli.php help getCDR
+./voipms-cli.php getCDR help
+```
+
+List locally documented commands:
+
+```bash
+./voipms-cli.php list
+```
+
+The CLI includes local help for the API areas most useful for small business
+automation, but the generic method caller can still call raw VoIP.ms methods
+that do not have local help yet.
+
+## Bash Completion
+
+The CLI can generate bash completion code:
+
+```bash
+source <(./voipms-cli.php completion bash)
+```
+
+After sourcing it, command completion works for both:
+
+```bash
+./voipms-cli.php <TAB><TAB>
+voipms-cli.php <TAB><TAB>
+```
+
+## Supported API Areas
+
+The current local command catalog covers:
+
+- Account balance, public IP, server info, and transaction history.
+- Subaccounts and registration status.
+- Call detail records, call account filters, call billing filters, and call
+  type filters.
+- Call recordings, recording download, and recording email.
+- DIDs, DID routing, DID information, CNAM lookup, and Caller ID prefix.
+- Forwarding rules, including Caller ID override.
+- Phonebook entries and phonebook groups.
+- CallerID Filtering rules.
+- SMS and MMS retrieval and sending.
+- Voicemail setup lookup.
+- Fax message lookup, PDF retrieval, and fax sending.
+- e911 lookup and validation.
+- Local Number Portability status and listing.
+
+## Friendlier Commands
+
+Some VoIP.ms API methods have awkward parameters. The CLI includes friendlier
+handling for the rougher ones.
+
+Call detail records can be queried with the `cdr` alias:
+
+```bash
+./voipms-cli.php cdr 2026-04-01 2026-04-20 --timezone=-4
+```
+
+The alias maps normal option names to the VoIP.ms parameter names and defaults
+to all call statuses (`answered`, `noanswer`, `busy`, and `failed`) because the
+API requires at least one status flag.
+
+Phonebook lookups also accept practical shortcuts:
+
+```bash
+./voipms-cli.php getPhonebook
+./voipms-cli.php getPhonebook 16389
+./voipms-cli.php getPhonebook Spam
+./voipms-cli.php getPhonebookGroups
+./voipms-cli.php getPhonebookGroups Spam
+```
+
+For `getPhonebook`, a bare numeric argument is treated as a phonebook group ID.
+A bare text argument is treated as a group name.
+
+## Phonebook And Caller ID Workflows
+
+Phonebook group membership is handled by VoIP.ms as a semicolon-separated list
+of phonebook entry IDs. A group can exist even when it has no entries, and the
+API may allow duplicate entries for the same number.
+
+Common commands:
+
+```bash
+./voipms-cli.php getPhonebookGroups
+./voipms-cli.php getPhonebook Spam
+./voipms-cli.php setPhonebook name="Jane Smith" number=5553334444 group=16389
+./voipms-cli.php setPhonebookGroup group=16389 name=Spam members="32207;32208"
+./voipms-cli.php delPhonebook phonebook=32207
+./voipms-cli.php delPhonebookGroup group=16389
+```
+
+CallerID Filtering commands are also included:
+
+```bash
+./voipms-cli.php getCallerIDFiltering
+./voipms-cli.php setCallerIDFiltering callerid=p:16389 did=all routing=sys:busy note="Spam group"
+./voipms-cli.php delCallerIDFiltering filtering=18915
+```
+
+## Library Overview
+
+The CLI is built on the reusable `VoipMs\VoipMsClient` class. The client can be
+used directly in PHP scripts:
+
+```php
+<?php
+
+require __DIR__ . '/src/VoipMsClient.php';
+
+use VoipMs\VoipMsClient;
+
+$client = new VoipMsClient(
+    getenv('VOIPMS_API_USERNAME'),
+    getenv('VOIPMS_API_PASSWORD'),
+);
+
+$response = $client->getPhonebookGroups();
+
+if (!$response->successful()) {
+    throw new RuntimeException($response->message() ?? 'VoIP.ms request failed.');
+}
+
+print_r($response->data());
+```
+
+The generic library API is:
+
+```php
+$response = $client->request('getDIDsInfo', ['did' => '5551234567']);
+```
+
+For compatibility with the CLI internals, `call()` still returns the older array
+shape:
+
+```php
+$result = $client->call('getBalance');
+echo $result['raw'];
+```
+
+Convenience methods are available for common workflows, including balance, DID
+lookup, CDR lookup, phonebook management, CallerID Filtering, call account
+filters, and SMS sending. See `docs/library.md` for examples.
+
+The library also includes helpers for safer phonebook group membership changes:
+
+```php
+$result = $client->addNumberToPhonebookGroup('5553334444', 'Spam');
+$result = $client->removePhonebookNumberFromGroup('16389', '5553334444');
+echo implode(', ', $result->removedEntryIds());
+```
+
+These helpers are standalone library features. They create or reuse phonebook
+groups and entries where appropriate, avoid adding duplicate group membership,
+and can remove matching phonebook entry IDs from a group without deleting the
+entries themselves.
+
+For call detail records and call recordings, `getAccounts` is provided as a
+friendly alias for VoIP.ms `getCallAccounts`. It returns account filter values,
+not VoIP.ms portal login users. Use the returned `value` field as the `account`
+argument for CDR and call recording commands.
+
+## Test MCP Server
+
+For remote-agent testing, the project includes a small HTTP JSON-RPC MCP server
+that wraps the standalone PHP library. It is meant for development and should
+be run behind a trusted network, firewall, VPN, or tunnel.
+
+Start it with:
+
+```bash
+export VOIPMS_API_USERNAME='you@example.com'
+export VOIPMS_API_PASSWORD='your-api-password'
+export MCP_AUTH_TOKEN='choose-a-long-random-token'
+
+./bin/serve-mcp.sh
+```
+
+By default it listens on:
+
+```text
+http://0.0.0.0:8787/mcp
+```
+
+The server exposes narrow tools for balance lookup, phonebook groups,
+phonebook entries, CallerID Filtering, CDR lookup, and dry-run-safe phonebook
+group mutations. See `docs/mcp.md` for curl examples and tool details.
+
+## Requirements
+
+- PHP 8.1 or newer.
+- PHP `curl` extension.
+- PHP `json` extension.
+
+Composer metadata is included for PSR-4 autoloading and bin registration, but
+the CLI can run directly without Composer:
+
+```bash
+./voipms-cli.php help
+```