proxy-cheap-client

Ruby client for the Proxy-Cheap.com API.

Features

• Retrieve account balance
• List proxies
• Enable/disable auto-extend on proxies
• Order new residential proxies

Requirements

• Ruby 2.7+
• Internet access to Proxy-Cheap.com API
• API key and API secret from Proxy-Cheap.com

Installation

Install from RubyGems:

gem install proxy-cheap-client

Or add to your Gemfile:

gem "proxy-cheap-client"

Then run:

bundle install

Configuration

The client requires both an API key and API secret.

You have to pass them explicitly when initializing the client:

client = ProxyCheapClient::Client.new(
  api_key: "your_api_key_here",
  api_secret: "your_api_secret_here"
)

Usage Example

require "proxy_cheap_client"

client = ProxyCheapClient::Client.new(
  api_key: "your_api_key_here",
  api_secret: "your_api_secret_here"
)

# 1. Get balance
balance = client.balance
puts "Balance: #{balance.amount} #{balance.currency}"

Load Proxies

proxies = client.proxies
proxies.each do |p|
  puts "Proxy #{p.id}: #{p.ip}:#{p.port}, auto_extend=#{p.auto_extend}"
end

Load Specific Proxy

proxy = ProxyCheapClient::Proxy.load(12345)
puts "Proxy details: #{proxy.to_h}"

Enable auto-extend for a proxy

proxy.enable_auto_extend
puts "Auto-extend enabled"

Disable auto-extend

proxy.disable_auto_extend
puts "Auto-extend disabled"

Supported Countries

arr = client.countries
puts "Supported Countries: #{arr}"

Order Residential Proxies

order = client.order_static_residential_proxy(
  country: "US",
  proxyProtocol: "HTTP",
  authenticationType: "USERNAME_PASSWORD"
)

Order Proxies

order.proxies

Error Handling

The client raises specific exceptions for failure modes:

• ProxyCheapClient::AuthenticationError - API key or secret is missing or invalid (HTTP 401)
• ProxyCheapClient::NotFoundError - Resource does not exist (HTTP 404)
• ProxyCheapClient::BadRequestError - Invalid request parameters (HTTP 400)
• ProxyCheapClient::ServerError - Server-side error (HTTP 5xx)
• ProxyCheapClient::RequestError - General request failure
• ProxyCheapClient::InvalidResponseError - Malformed or non-JSON response

All errors inherit from ProxyCheapClient::Error and include status_code and response_body attributes for debugging:

begin
  client.balance
rescue ProxyCheapClient::NotFoundError => e
  puts "Not found: #{e.message}"
  puts "Status: #{e.status_code}"
  puts "Body: #{e.response_body}"
rescue ProxyCheapClient::Error => e
  puts "API failure: #{e.message}"
end

Publishing

Build and push to RubyGems:

gem build proxy-cheap-client.gemspec
gem push proxy-cheap-client-#{ProxyCheapClient::VERSION}.gem

Make sure you have an account on RubyGems.org and appropriate credentials configured in ~/.gem/credentials.

Contributing

1. Fork the repository.
2. Create a feature branch: git checkout -b feature/xyz
3. Run tests (add test suite if missing).
4. Open a pull request with a clear description.

License

This project is licensed under the MIT License. See LICENSE.txt for details.