proxy-cheap-client

Ruby client for the Proxy-Cheap.com API.

Features:

• Retrieve account balance
• List proxies
• Enable/disable auto-extend on proxies
• Get list of supported countries
• Order new residential proxies

Requirements:

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

Outlook:

• 1. Installation
• 2. Configuration
• 3. Usage Example
• 4. Load Proxies
• 5. Load Specific Proxy
• 6. Enable auto-extend for a proxy
• 7. Disable auto-extend
• 8. Supported Countries
• 9. Order Residential Proxies
• 10. Order Proxies
• 11. Order Expenses
• 12. Proxies of an Old Order
• 13. Using Multiple Credentials
• 14. Error Handling
• 15. Publishing
• 16. Contributing
• 17. License

1. Installation

gem install proxy-cheap-client

2. 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"
)

3. 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}"

4. Load Proxies

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

5. Load Specific Proxy

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

6. Enable auto-extend for a proxy

proxy.enable_auto_extend
puts "Auto-extend enabled"

7. Disable auto-extend

proxy.disable_auto_extend
puts "Auto-extend disabled"

8. Supported Countries

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

9. Order Residential Proxies

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

10. Order Proxies

order.proxies

11. Order Expenses

puts "Total Price: #{order.total_price} USD"
# => "Total Price: 3.39 USD"

12. Proxies of an Old Order

# Get proxies for an order by Order ID
proxies = client.order_proxies("019b85aa-7e12-7b10-a26e-46fc5adfdcf4")
proxies.each do |p|
  puts "Proxy #{p.id}: #{p.ip}:#{p.port}"
end
# => Proxy 1742085: 176.46.143.42:45842
# => ...

13. Using Multiple Credentials

...

# Reset the client connection
ProxyCheapClient::Client.reset_connection

# Initialize the client with other API credentials.
client = ProxyCheapClient::Client.new(
  api_key: PROXY_CHEAP_API_KEY,
  api_secret: PROXY_CHEAP_API_SECRET
)

14. 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

15. 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.

16. 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.

17. License

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