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();
}

cosmotown / api-client

Maintainers

Package info

Statistics

Security