# SpryConnect PHP SDK

Official PHP SDK for the SpryConnect API - Send SMS, generate OTPs, and manage contacts with ease.

## Installation

Install via Composer:

```bash
composer require spryconnect/php-sdk
```

## Requirements

- PHP 8.0 or higher
- Guzzle HTTP client

## Quick Start

```php
<?php

require 'vendor/autoload.php';

use SpryConnect\SDK\SpryConnectClient;

// Initialize the client
$client = new SpryConnectClient(
    apiKey: 'your-api-key',
    apiSecret: 'your-api-secret'
);

// Send a quick SMS
$response = $client->sms->sendQuick([
    'to' => '233XXXXXXXXX',
    'from' => 'YourBrand',
    'message' => 'Hello from SpryConnect!'
]);

echo "Message sent! ID: " . $response->id;
```

## Features

- ✅ **SMS Messaging** - Send quick and bulk SMS with scheduling
- ✅ **OTP Verification** - Generate and verify one-time passwords
- ✅ **Contact Management** - Organize contacts into groups
- ✅ **Account Management** - Check balance, usage stats, and delivery rates
- ✅ **Type-safe** - Full PHP 8.0+ type hints
- ✅ **Exception handling** - Comprehensive error handling
- ✅ **PSR-12 compliant** - Follows PHP coding standards

## Usage Examples

### SMS Operations

#### Send Quick SMS
```php
$response = $client->sms->sendQuick([
    'to' => '233XXXXXXXXX',
    'from' => 'YourBrand',
    'message' => 'Your message here'
]);
```

#### Send Bulk SMS
```php
$response = $client->sms->sendBulk([
    'messages' => [
        [
            'to' => '233XXXXXXXXX',
            'from' => 'YourBrand',
            'message' => 'Message 1'
        ],
        [
            'to' => '233YYYYYYYYY',
            'from' => 'YourBrand',
            'message' => 'Message 2'
        ]
    ]
]);
```

#### Schedule SMS
```php
$response = $client->sms->sendQuickScheduled([
    'to' => '233XXXXXXXXX',
    'from' => 'YourBrand',
    'message' => 'Scheduled message',
    'scheduled_at' => '2026-01-15 10:00:00'
]);
```

#### Check Message Status
```php
$status = $client->sms->checkMessageStatus($messageId);
```

#### Get Message Logs
```php
$logs = $client->sms->getMessageLogs([
    'isPaginated' => true,
    'page' => 1,
    'limit' => 15
]);
```

### OTP Operations

#### Generate OTP
```php
$response = $client->otp->generate([
    'recipient' => '233XXXXXXXXX',
    'from' => 'YourBrand',
    'message' => 'Your verification code is {code}',
    'pinLength' => 6,
    'expiryMinutes' => 5
]);
```

#### Verify OTP
```php
$isValid = $client->otp->verify([
    'recipient' => '233XXXXXXXXX',
    'code' => '123456'
]);
```

### Account Operations

#### Check Balance
```php
$balance = $client->account->checkBalance();
echo "Balance: " . $balance->balance;
```

#### Get Usage Statistics
```php
$stats = $client->account->getUsageStatistics();
```

#### Get Delivery Rates
```php
$rates = $client->account->getDeliveryRates([
    'startDate' => '2026-01-01',
    'endDate' => '2026-01-31'
]);
```

### Contact Management

#### List Contact Groups
```php
$groups = $client->contacts->listGroups();
```

#### Create Contact Group
```php
$group = $client->contacts->createGroup([
    'group_name' => 'VIP Customers',
    'description' => 'Our premium customers',
    'contact_type' => 'SMS',
    'status' => 'Active'
]);
```

#### Get Single Group
```php
$group = $client->contacts->getGroup($groupId);
```

#### Update Contact Group
```php
$updated = $client->contacts->updateGroup($groupId, [
    'group_name' => 'Updated Name',
    'description' => 'Updated description'
]);
```

#### Delete Contact Group
```php
$client->contacts->deleteGroup($groupId);
```

## Error Handling

The SDK throws specific exceptions for different error scenarios:

```php
use SpryConnect\SDK\Exceptions\ApiException;
use SpryConnect\SDK\Exceptions\AuthenticationException;
use SpryConnect\SDK\Exceptions\RateLimitException;
use SpryConnect\SDK\Exceptions\ValidationException;

try {
    $response = $client->sms->sendQuick([
        'to' => '233XXXXXXXXX',
        'from' => 'YourBrand',
        'message' => 'Test message'
    ]);
} catch (AuthenticationException $e) {
    // Invalid API credentials
    echo "Authentication failed: " . $e->getMessage();
} catch (ValidationException $e) {
    // Invalid parameters
    echo "Validation error: " . $e->getMessage();
} catch (RateLimitException $e) {
    // Rate limit exceeded
    echo "Rate limit exceeded. Retry after: " . $e->getRetryAfter();
} catch (ApiException $e) {
    // General API error
    echo "API error: " . $e->getMessage();
}
```

## Configuration

### Custom Base URL
```php
$client = new SpryConnectClient(
    apiKey: 'your-api-key',
    apiSecret: 'your-api-secret',
    baseUrl: 'https://custom-api.spryconnect.com'
);
```

### Custom Timeout
```php
$client = new SpryConnectClient(
    apiKey: 'your-api-key',
    apiSecret: 'your-api-secret',
    timeout: 30 // seconds
);
```

## Testing

Run the test suite:

```bash
composer test
```

## Support

- **Documentation:** https://docs.spryconnect.com
- **Email:** support@spryconnect.com
- **Issues:** https://github.com/spryconnect/php-sdk/issues

## License

This SDK is open-sourced software licensed under the [MIT license](LICENSE).
