README

A robust, strongly-typed PHP library for interacting with the Cosmotown Reseller API.

This library provides an object-oriented wrapper around the Cosmotown endpoints, transforming raw JSON responses into explicitly typed Data Transfer Objects (DTOs) and handling common HTTP errors gracefully with custom exceptions.

Requirements

• PHP 8.1 or higher
• GuzzleHTTP ^7.8

Installation

You can install the package via composer:

composer require cosmotown/api-client

(Note: If this is used as a local repository, ensure you dump autoloads first via composer dump-autoload.)

Authentication & Initialization

To use the API, you must have an API token generated from your Cosmotown Reseller dashboard. Cosmotown provides a Test Server Environment called "Sandbox". You can enable sandbox endpoints by passing true as the second argument to the Client.

use Cosmotown\Api\Client;

// For Production
$client = new Client('YOUR_PRODUCTION_API_KEY');

// For Sandbox (Testing environment)
$client = new Client('YOUR_SANDBOX_API_KEY', true);

Usage Examples

All responses are properly typed. IDEs with autocompletion (like PhpStorm or VS Code) will suggest all properties natively.

1. Get My Domains

Fetches a list of domains currently registered to your reseller account.

$domains = $client->getMyDomains(limit: 50, offset: 0);

foreach ($domains as $domainEntry) {
    echo $domainEntry->domain . " expires on " . $domainEntry->expirationDate . "\n";
    // Accessible properties:
    // $domainEntry->autoBilling (bool)
    // $domainEntry->whoisPrivacy (bool)
    // $domainEntry->locked (bool)
    // $domainEntry->created (?string)
}

2. Search Domain Availability

Allows batch querying for domain name availability via public RDAP.

Note: Since this leverages public RDAP infrastructure rather than Cosmotown internal pricing data, the $price attribute will currently be null.

$searchQuery = [
    'exampledomain.com',
    'exampledomain2.net'
];

$results = $client->searchDomains($searchQuery);

foreach ($results as $result) {
    if ($result->isAvailable()) {
        echo "{$result->domain} is available!\n";
    } else {
        echo "Sorry, {$result->domain} is: {$result->message}\n";
    }
}

3. Get Domain Information

Get detailed information about a single domain, including nameservers and contact information.

$domainInfo = $client->getDomainInfo('exampledomain.com');

echo "Nameservers: " . implode(", ", $domainInfo->nameservers) . "\n";
echo "Registrant Email: " . $domainInfo->contact->registrant->email . "\n";
echo "Billing Phone: " . $domainInfo->contact->billing->phone . "\n";

4. Register a Domain

Register new domains specifying the registration length in years. (This workflow is asynchronous on the Cosmotown side.)

$items = [
    ['name' => 'newdomain1.com', 'years' => 1],
    ['name' => 'newdomain2.net', 'years' => 2]
];

// Provide an optional coupon code as the second parameter if you have one
$results = $client->registerDomains($items, 'MY_COUPON');

foreach ($results as $registration) {
    echo "{$registration->domain} Status: {$registration->status}\n";
}

5. Managing Domains (Nameservers & Options)

Update nameservers or toggle privacy, locks, and auto-billing.

// Update nameservers
$client->saveDomainNameservers('exampledomain.com', [
    'ns1.cosmotown.com',
    'ns2.cosmotown.com'
]);

// Change Domain Options
$success = $client->changeDomainOptions('exampledomain.com', [
    'enable_private_whois' => true,
    'lock_domain' => true,
    'enable_auto_billing' => false
]);

if ($success) {
    echo "Options successfully updated!";
}

6. Managing Domain Contacts

You can update the primary contacts linked to a domain.

use Cosmotown\Api\Models\Contact;
use Cosmotown\Api\Models\ContactSet;

// Create Contact entries
$registrant = new Contact(
    firstName: 'John',
    lastName: 'Doe',
    company: 'Acme Corp',
    phone: '+1.5555555555',
    extension: '',
    fax: '',
    city: 'New York',
    state: 'NY',
    zip: '10001',
    country: 'USA',
    email: 'john@example.com',
    address1: '123 Main St',
    address2: ''
);

// Map different contact roles (they can reuse the same Contact object)
$contactSet = new ContactSet(
    registrant: $registrant,
    administrative: $registrant,
    technical: $registrant,
    billing: $registrant
);

$updatedDomainInfo = $client->saveDomainContactInformation('exampledomain.com', $contactSet);

7. Actions: Transfer, Renew, and Auth Code

// Renew Domains
$success = $client->renewDomains([
    ['name' => 'exampledomain.com', 'years' => 1]
]);

// Transfer Domains
$transferResult = $client->transferDomains([
    ['name' => 'transferme.com', 'authCode' => base64_encode('YourAuthCode123!')]
]);

// Get Auth/EPP Code for outbound transfers
$authCode = $client->getDomainAuthCode('exampledomain.com');
echo "EPP Code: " . $authCode;

Error Handling

The library catches Guzzle requests and maps specific backend HTTP status codes to typed exceptions for easy granular try/catch control flow:

• 400 Bad Request throws Cosmotown\Api\Exceptions\ValidationException (Unsuccessful request due to missing arguments)
• 403 Forbidden throws Cosmotown\Api\Exceptions\UnauthorizedException (Invalid IP or Bad API Key)
• 429 Too Many Requests throws Cosmotown\Api\Exceptions\RateLimitException
• 500 Server Error throws Cosmotown\Api\Exceptions\ServerException

All of these extend the base CosmotownException class.

use Cosmotown\Api\Exceptions\RateLimitException;
use Cosmotown\Api\Exceptions\UnauthorizedException;
use Cosmotown\Api\Exceptions\CosmotownException;

try {
    $client->getMyDomains();
} catch (UnauthorizedException $e) {
    // API key revoked or bad IP
    echo "Auth failed: " . $e->getMessage();
} catch (RateLimitException $e) {
    // Wait before requesting again
    echo "Slow down: " . $e->getMessage();
} catch (CosmotownException $e) {
    // Generic catch-all API error
    echo "General API Error: " . $e->getMessage();
}