two_captcha 1.6.0 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85dec926f62d43f6629fea1232276b55950cac27c107e64d064f6374f571c6b6
-  data.tar.gz: 9e962be8d8d1dd76f6cfe7644003a042b3bcccf216aa5d820fd057c95d930c22
+  metadata.gz: c6657c4e05fd2c0a00072c9070954b73b1a5573ab9a6896301b2836098aeea66
+  data.tar.gz: ea035f063342b484e83272b2a75838fa4ce1b4b02b2c25a3a49e53b666ecb0d4
 SHA512:
-  metadata.gz: 11dc25d38866f051f13963f460c9b8d5b813d0960b4f1ce8fa3b0c589555d368021cae3994cd1e9d0e6f730940a6921fa91173a70e48a29ec25b7a3903ac814e
-  data.tar.gz: 762fd992e1b9fa35cfc91baf729d280d123298a46f92b75a6dc03e3b42294184d3a4c84cfc449b5d6d44615f54434c5a1d9c0b565ce1ab7d310cf907996b0d50
+  metadata.gz: ab1e833fbf80a57058f7e78a4b6399473fd56606247c34081212cbd9205ba7f9d6ab6a091a415a9db48d7b55ffe736ec2267c48a76adfa02764d3a4373c5d6f5
+  data.tar.gz: 525b2cd2321e4e2ac9f35ec56a5f05c3ebc0d95ab7d0564e7c31d0c0a38f9a656e6fb7536224452174d3be10c33d5922d2b4d099e76ee78a678f22a1dfb5d6b1

data/README.md

@@ -1,8 +1,9 @@
-Developed by [Infosimples](https://infosimples.com).
-
 # TwoCaptcha
 
-TwoCaptcha is a Ruby API for 2Captcha - [2Captcha.com](http://2captcha.com/?from=1025109).
+TwoCaptcha is a Ruby API for 2Captcha - [2Captcha.com](http://2captcha.com/?from=1025109)
+
+> We suggest you to also check the recommended CAPTCHA provider DeathByCaptcha.
+> The gem for this provider is available at https://github.com/infosimples/deathbycaptcha.
 
 ## Installation
 
@@ -14,249 +15,197 @@ gem 'two_captcha'
 
 And then execute:
 
-    $ bundle
+```bash
+$ bundle
+````
 
 Or install it yourself as:
 
-    $ gem install two_captcha
+```bash
+$ gem install two_captcha
+````
 
 ## Usage
 
-1. **Create a client**
-
-  ```ruby
-  # Create a client
-  client = TwoCaptcha.new('my_captcha_key')
-  ```
-
-2. **Solve a captcha**
-
-  There are two methods available: **decode** and **decode!**
-    * **decode** doesn't raise exceptions.
-    * **decode!** may raise a *TwoCaptcha::Error* if something goes wrong.
-
-  If the solution is not available, an empty captcha object will be returned.
-
-  ```ruby
-  captcha = client.decode!(url: 'http://bit.ly/1xXZcKo')
-  captcha.text        # Solution of the captcha
-  captcha.id          # Numeric ID of the captcha solved by TwoCaptcha
-  ```
-
-  You can also specify *path*, *file*, *raw* and *raw64* when decoding an image.
-
-  ```ruby
-  client.decode(path: 'path/to/my/captcha/file')
-
-  client.decode(file: File.open('path/to/my/captcha/file', 'rb'))
-
-  client.decode(raw: File.open('path/to/my/captcha/file', 'rb').read)
-
-  client.decode(raw64: Base64.encode64(File.open('path/to/my/captcha/file', 'rb').read))
-  ```
-
-  > Internally, the gem will always convert the image to raw64 (binary base64 encoded).
-
-  You may also specify any POST parameters specified at
-  https://2captcha.com/setting.
+### 1. Create a client
 
-3. **Retrieve a previously solved captcha**
-
-  ```ruby
-  captcha = client.captcha('130920620') # with 130920620 as the captcha id
-  ```
-
-4. **Report incorrectly (for refund) or correctly (useful for reCAPTCHA v3) solved captcha**
-
-  ```ruby
-  client.report!('130920620', 'reportbad') # with 130920620 as the captcha id
-  # return true if successfully reported
-
-  client.report!('256892751', 'reportgood') # with 256892751 as the captcha id
-  # return true if successfully reported
-  ```
-
-  > ***Warning:*** *do not abuse on this method, otherwise you may get banned*
-
-5. **Get your balance on 2Captcha**
-
-  ```ruby
-  client.balance
-  # return a Float balance in USD.
-  ```
+```ruby
+client = TwoCaptcha.new('my_key')
+```
 
-6. **Get usage statistics for a specific date**
+### 2. Solve a CAPTCHA
 
-  ```ruby
-  client.stats('2015-08-05')
-  # return an XML string with your usage statistics.
-  ```
+There are two types of methods available: `decode` and `decode!`:
 
-7. **Get current 2Captcha load**
+- `decode` does not raise exceptions.
+- `decode!` may raise a `TwoCaptcha::Error` if something goes wrong.
 
-  ```ruby
-  client.load
-  # return an XML string with the current service load.
-  ```
+If the solution is not available, an empty solution object will be returned.
 
-## reCAPTCHA v2 (e.g. "No CAPTCHA reCAPTCHA")
+```ruby
+captcha = client.decode_image!(url: 'http://bit.ly/1xXZcKo')
+captcha.text        # CAPTCHA solution
+captcha.id          # CAPTCHA numeric id
+```
 
-There are two ways of solving captchas similar to
-[reCAPTCHA v2](https://support.google.com/recaptcha/?hl=en#6262736).
+#### Image CAPTCHA
 
-### (Prefered) Sending the `googlekey` and `pageurl` parameters
+You can specify `file`, `path`, `raw`, `raw64` and `url` when decoding an image.
 
-This method requires no browser emulation. You can send two parameters that
-identify the website in which the captcha is found.
+```ruby
+client.decode_image!(file: File.open('path/to/my/captcha/file', 'rb'))
+client.decode_image!(path: 'path/to/my/captcha/file')
+client.decode_image!(raw: File.open('path/to/my/captcha/file', 'rb').read)
+client.decode_image!(raw64: Base64.encode64(File.open('path/to/my/captcha/file', 'rb').read))
+client.decode_image!(url: 'http://bit.ly/1xXZcKo')
+```
 
-Please read the [oficial documentation](https://2captcha.com/newapi-recaptcha-en)
-for more information.
+You may also specify any POST parameters specified at https://2captcha.com/setting.
 
-  ```ruby
-  options = {
-    googlekey: 'xyz',
-    pageurl: 'http://example.com/example=1'
-  }
+#### reCAPTCHA v2
 
-  captcha = client.decode_recaptcha_v2(options)
-  captcha.text        # Solution of the captcha
-  captcha.id          # Numeric ID of the captcha solved by TwoCaptcha
-  ```
+```ruby
+captcha = client.decode_recaptcha_v2!(
+  googlekey: 'xyz',
+  pageurl:   'http://example.com/example=1',
+)
 
-  The solution (`captcha.text`) will be a code that validates the form, like the
-  following:
+# The response will be a text (token), which you can access with the `text` method.
 
-  ```ruby
-  "1JJHJ_VuuHAqJKxcaasbTsqw-L1Sm4gD57PTeaEr9-MaETG1vfu2H5zlcwkjsRoZoHxx6V9yUDw8Ig-hYD8kakmSnnjNQd50w_Y_tI3aDLp-s_7ZmhH6pcaoWWsid5hdtMXyvrP9DscDuCLBf7etLle8caPWSaYCpAq9DOTtj5NpSg6-OeCJdGdkjsakFUMeGeqmje87wSajcjmdjl_w4XZBY2zy8fUH6XoAGZ6AeCTulIljBQDObQynKDd-rutPvKNxZasDk-LbhTfw508g1lu9io6jnvm3kbAdnkfZ0x0PkGiUMHU7hnuoW6bXo2Yn_Zt5tDWL7N7wFtY6B0k7cTy73f8er508zReOuoyz2NqL8smDCmcJu05ajkPGt20qzpURMwHaw"
-  ```
+captcha.text
+"03AOPBWq_RPO2vLzyk0h8gH0cA2X4v3tpYCPZR6Y4yxKy1s3Eo7CHZRQntxrd..."
+```
 
-### Sending the challenge image
+*Parameters:*
 
-You can add the param `coordinatescaptcha: 1` to your request.
+- `googlekey`: the Google key for the reCAPTCHA.
+- `pageurl`: the URL of the page with the reCAPTCHA challenge.
 
-Please read the oficial documentation at https://2captcha.com/en-api-recaptcha for
-more information.
 
-  ```ruby
-  client.decode(url: 'http://bit.ly/clickcaptcha', coordinatescaptcha: 1)
-  ```
+#### reCAPTCHA v3
 
-**Captcha (screenshot)**
+```ruby
+captcha = client.decode_recaptcha_v3!(
+  googlekey: 'xyz',
+  pageurl:   'http://example.com/example=1',
+  action:    'verify',
+  min_score: 0.3, # OPTIONAL
+)
 
-> the argument is passed as *url*, *path*, *file*, *raw* or *raw64*
+# The response will be a text (token), which you can access with the `text` method.
 
-![Example of a captcha based on image clicks](captchas/2.jpg)
+captcha.text
+"03AOPBWq_RPO2vLzyk0h8gH0cA2X4v3tpYCPZR6Y4yxKy1s3Eo7CHZRQntxrd..."
+```
 
-The response will be an array containing coordinates where the captcha should be
-clicked. For the captcha above it should look something like:
+*Parameters:*
 
-  ```ruby
-  # captcha.text
-  "coordinates:x=50.66999816894531,y=130.3300018310547;x=236.66998291015625,y=328.3299865722656"
-  ```
+- `googlekey`: the Google key for the reCAPTCHA.
+- `pageurl`: the URL of the page with the reCAPTCHA challenge.
+- `action`: the action name used by the CAPTCHA.
+- `min_score`: optional parameter. The minimal score needed for the CAPTCHA resolution. Defaults to `0.3`.
 
-## Audio reCAPTCHA v2
+> About the `action` parameter: in order to find out what this is, you need to inspect the JavaScript
+> code of the website looking for a call to the `grecaptcha.execute` function.
+>
+> ```javascript
+> // Example
+> grecaptcha.execute('6Lc2fhwTAAAAAGatXTzFYfvlQMI2T7B6ji8UVV_f', { action: "examples/v3scores" })
+> ````
 
-  ```ruby
-  client.decode(url: 'http://bit.ly/audiorecaptchav2', recaptchavoice: 1)
-  ```
+> About the `min_score` parameter: it's strongly recommended to use a minimum score of `0.3` as higher
+> scores are rare.
 
-The response will be a simple text:
+#### hCaptcha
 
 ```ruby
-# captcha.text
-'61267'
+captcha = client.decode_hcaptcha!(
+  sitekey: 'xyz',
+  pageurl: 'http://example.com/example=1',
+)
+
+captcha.text
+"P0_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwYXNza2V5IjoiNnpWV..."
 ```
 
-## reCAPTCHA v3
+*Parameters:*
 
-This method requires no browser emulation. You can send four parameters that
-identify the website in which the CAPTCHA is found and the minimum score
-(0.3, 0.5 or 0.7) you desire.
+- `website_key`: the site key for the hCatpcha.
+- `website_url`: the URL of the page with the hCaptcha challenge.
 
-**It's strongly recommended to use a minimum score of 0.3 as higher scores are extremely rare.**
+### 3. Using proxy or other custom options
 
-Please read the [oficial documentation](https://2captcha.com/2captcha-api#solving_recaptchav3)
-for more information.
+You are allowed to use custom options like `proxy`, `proxytype` or `userAgent` whenever the
+2Captcha API supports it. Example:
 
   ```ruby
   options = {
-    googlekey: 'xyz',
+    sitekey:   'xyz',
     pageurl:   'http://example.com/example=1',
-    action:    'verify',
-    min_score: 0.3
+    proxy:     'login:password@123.123.123.123:3128',
+    userAgent: 'user agent',
   }
 
-  captcha = client.decode_recaptcha_v3(options)
-  captcha.text        # Solution of the captcha
-  captcha.id          # Numeric ID of the captcha solved by TwoCaptcha
+  captcha = client.decode_hcaptcha!(options)
   ```
 
-The solution (`captcha.text`) will be a code that validates the form, like the
-following:
+### 4. Retrieve a previously solved CAPTCHA
 
-  ```ruby
-  "1JJHJ_VuuHAqJKxcaasbTsqw-L1Sm4gD57PTeaEr9-MaETG1vfu2H5zlcwkjsRoZoHxx6V9yUDw8Ig-hYD8kakmSnnjNQd50w_Y_tI3aDLp-s_7ZmhH6pcaoWWsid5hdtMXyvrP9DscDuCLBf7etLle8caPWSaYCpAq9DOTtj5NpSg6-OeCJdGdkjsakFUMeGeqmje87wSajcjmdjl_w4XZBY2zy8fUH6XoAGZ6AeCTulIljBQDObQynKDd-rutPvKNxZasDk-LbhTfw508g1lu9io6jnvm3kbAdnkfZ0x0PkGiUMHU7hnuoW6bXo2Yn_Zt5tDWL7N7wFtY6B0k7cTy73f8er508zReOuoyz2NqL8smDCmcJu05ajkPGt20qzpURMwHaw"
-  ```
+```ruby
+captcha = client.captcha('130920620') # with 130920620 being the CAPTCHA id
+```
 
-## hCaptcha
+### 5. Report an incorrectly solved CAPTCHA for a refund
 
-  This method allows you to solve hCaptcha.
+```ruby
+client.report!('130920620', 'reportbad') # with 130920620 being the CAPTCHA id
+# returns `true` if successfully reported
 
-  There are two methods available:
+client.report!('256892751', 'reportgood') # with 256892751 being the CAPTCHA id
+# returns `true` if successfully reported
+```
 
-  - `decode_hcaptcha`: solves hCaptcha CAPTCHAs. It doesn't raise exceptions.
-  - `decode_hcaptcha!`: solves hCaptcha CAPTCHAs. It may raise an error if something goes wrong.
+### 6. Get your account balance
 
-  **Send the `sitekey` and `pageurl` parameters**
+```ruby
+client.balance
+# returns a Float balance in USD.
+```
 
-  This method requires no browser emulation. You can send two parameters that
-  identify the website in which the CAPTCHA is found.
+### 7. Get usage statistics for a specific date
 
-  ```ruby
-  options = {
-    sitekey: 'xyz',
-    pageurl: 'http://example.com/example=1'
-  }
-
-  captcha = client.decode_hcaptcha!(options)
-  captcha.text # Solution of the captcha
-  ```
+```ruby
+client.stats(Date.new(2022, 10, 7))
+# returns an XML string with your usage statistics.
+```
 
 ## Notes
 
-#### Thread-safety
+### Thread-safety
 
 The API is thread-safe, which means it is perfectly fine to share a client
 instance between multiple threads.
 
-#### Ruby dependencies
+### Ruby dependencies
 
 TwoCaptcha don't require specific dependencies. That saves you memory and
 avoid conflicts with other gems.
 
-#### Input image format
+### Input image format
 
-Any format you use in the decode method (url, file, path, raw, raw64) will
-always be converted to a raw64, which is a binary base64 encoded string. So, if
-you already have this format available on your side, there's no need to do
-convertions before calling the API.
+Any format you use in the `decode_image!` method (`url`, `file`, `path`, `raw` or `raw64`)
+will always be converted to a `raw64`, which is a base64-encoded binary string.
+So, if you already have this format on your end, there is no need for convertions
+before calling the API.
 
 > Our recomendation is to never convert your image format, unless needed. Let
 > the gem convert internally. It may save you resources (CPU, memory and IO).
 
-#### Versioning
+### Versioning
 
 TwoCaptcha gem uses [Semantic Versioning](http://semver.org/).
 
-#### Tested Ruby versions
-
-* MRI 2.2.2
-* MRI 2.2.0
-* MRI 2.1.4
-* MRI 2.0.0
-
-## Contributing
+### Contributing
 
 1. Fork it ( https://github.com/infosimples/two_captcha/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
@@ -272,4 +221,4 @@ https://github.com/infosimples/two_captcha/graphs/contributors
 
 # License
 
-MIT License. Copyright (C) 2011-2015 Infosimples. https://infosimples.com/
+MIT License. Copyright (C) 2011-2022 Infosimples. https://infosimples.com/

data/lib/two_captcha/client.rb

@@ -18,9 +18,9 @@ module TwoCaptcha
     # @return [TwoCaptcha::Client] A Client instance.
     #
     def initialize(key, options = {})
-      self.key    = key
-      self.timeout  = options[:timeout] || 60
-      self.polling  = options[:polling] || 5
+      self.key     = key
+      self.timeout = options[:timeout] || 60
+      self.polling = options[:polling] || 5
     end
 
     # Decode the text from an image (i.e. solve a captcha).
@@ -30,11 +30,12 @@ module TwoCaptcha
     # @return [TwoCaptcha::Captcha] The captcha (with solution) or an empty
     #                               captcha instance if something goes wrong.
     #
-    def decode(options = {})
-      decode!(options)
+    def decode_image(options = {})
+      decode_image!(options)
     rescue TwoCaptcha::Error => ex
       TwoCaptcha::Captcha.new
     end
+    alias :decode :decode_image
 
     # Decode the text from an image (i.e. solve a captcha).
     #
@@ -60,7 +61,7 @@ module TwoCaptcha
     # @return [TwoCaptcha::Captcha] The captcha (with solution) if an error is
     #                               not raised.
     #
-    def decode!(options = {})
+    def decode_image!(options = {})
       started_at = Time.now
 
       raw64 = load_captcha(options)
@@ -77,6 +78,7 @@ module TwoCaptcha
 
       decoded_captcha
     end
+    alias :decode! :decode_image!
 
     #
     # Solve reCAPTCHA v2.
@@ -105,11 +107,7 @@ module TwoCaptcha
 
       fail(TwoCaptcha::GoogleKey) if options[:googlekey].empty?
 
-      upload_options = {
-        method: 'userrecaptcha',
-        googlekey: options[:googlekey],
-        pageurl: options[:pageurl]
-      }
+      upload_options = { method: 'userrecaptcha' }.merge(options)
       decoded_captcha = upload(upload_options)
 
       # pool untill the answer is ready
@@ -152,13 +150,9 @@ module TwoCaptcha
       fail(TwoCaptcha::GoogleKey) if options[:googlekey].empty?
 
       upload_options = {
-        method:    'userrecaptcha',
-        version:   'v3',
-        googlekey: options[:googlekey],
-        pageurl:   options[:pageurl],
-        action:    options[:action],
-        min_score: options[:min_score]
-      }
+        method:  'userrecaptcha',
+        version: 'v3',
+      }.merge(options)
       decoded_captcha = upload(upload_options)
 
       # pool untill the answer is ready
@@ -196,13 +190,9 @@ module TwoCaptcha
     def decode_hcaptcha!(options = {})
       started_at = Time.now
 
-      fail(TwoCaptcha::GoogleKey) if options[:sitekey].empty?
+      fail(TwoCaptcha::SiteKey) if options[:sitekey].empty?
 
-      upload_options = {
-        method:    'hcaptcha',
-        sitekey:   options[:sitekey],
-        pageurl:   options[:pageurl]
-      }
+      upload_options = { method: 'hcaptcha' }.merge(options)
       decoded_captcha = upload(upload_options)
 
       # pool untill the answer is ready

data/lib/two_captcha/version.rb

@@ -1,4 +1,4 @@
 module TwoCaptcha
-  VERSION = '1.6.0'
+  VERSION = '1.8.0'
   USER_AGENT = "TwoCaptcha/Ruby v#{VERSION}"
 end

data/two_captcha.gemspec

@@ -22,7 +22,7 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.8"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "bundler", ">= 2.2.33"
+  spec.add_development_dependency "rake", ">= 12.3.3"
   spec.add_development_dependency "rspec", "~> 3.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: two_captcha
 version: !ruby/object:Gem::Version
-  version: 1.6.0
+  version: 1.8.0
 platform: ruby
 authors:
 - Rafael Barbolo
@@ -9,36 +9,36 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-01-26 00:00:00.000000000 Z
+date: 2022-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.8'
+        version: 2.2.33
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.8'
+        version: 2.2.33
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: 12.3.3
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: 12.3.3
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -103,7 +103,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.6
+rubygems_version: 3.1.4
 signing_key:
 specification_version: 4
 summary: Ruby API for 2Captcha (Captcha Solver as a Service)