Merge pull request #13 from 2captcha/RC-2646

RC-2646 Add Grid method

Author: dzmitry-duboyski

README.md

@@ -25,6 +25,7 @@ The easiest way to quickly integrate the [2Captcha](https://2captcha.com/) captc
     - [MTCaptcha](#mtcaptcha)
     - [Friendly Captcha](#friendly-captcha)
     - [Bounding Box Method](#bounding-box-method)
+    - [Grid](#grid)
   - [Other methods](#other-methods)
     - [goodReport](#goodreport)
     - [badReport](#badreport)
@@ -440,7 +441,7 @@ solver.coordinates({
 })
 ```
 
-### Bounding Box Method:
+### Bounding Box Method
 
 <sup>[API method description.](https://2captcha.com/2captcha-api#bounding_box)</sup>
 
@@ -462,6 +463,28 @@ solver.boundingBox({
 })
 ```
 
+### Grid
+
+<sup>[API method description.](https://2captcha.com/2captcha-api#grid)</sup>
+
+This method allows to solve any captcha where image can be divided into equal parts like reCAPTCHA V2 or hCaptcha. A grid is applied above the image. And you receive the numbers clicked boxes.
+
+> [!IMPORTANT]  
+> You must to send instruction `imginstructions` or `textinstructions`.
+
+```js
+solver.grid({ 
+  body: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAR4AAACwCAIAAAB...",
+  textinstructions: "Select cars in the image"
+})
+.then((res) => {
+    console.log(res);
+})
+.catch((err) => {
+    console.log(err);
+})
+```
+
 ## Other methods
 
 ### goodReport

examples/boundingBox.js

@@ -0,0 +1,17 @@
+const TwoCaptcha = require("../dist/index.js");
+require('dotenv').config();
+const APIKEY = process.env.APIKEY
+const solver = new TwoCaptcha.Solver(APIKEY);
+const fs = require('fs')
+const imageBase64 = fs.readFileSync("./media/recaptchaGrid3x3.jpg", "base64")
+
+solver.grid({
+  body: imageBase64,
+  textinstructions: "Select cars in the image"
+})
+.then((res) => {
+    console.log(res);
+})
+.catch((err) => {
+    console.log(err);
+})

examples/grid.js

@@ -0,0 +1,27 @@
+const TwoCaptcha = require("../dist/index.js");
+require("dotenv").config();
+const APIKEY = process.env.APIKEY;
+const solver = new TwoCaptcha.Solver(APIKEY);
+const fs = require("fs");
+const imageBase64 = fs.readFileSync("./media/recaptchaGrid4x4.jpg", "base64");
+const imageInstructionsBase64 = fs.readFileSync("./media/recaptchaGridImginstructions4x4.jpg", "base64");
+
+solver.grid({
+    body: imageBase64,
+    textinstructions: "Select all squares with stairs",
+    imginstructions: imageInstructionsBase64,
+    cols: 4,
+    rows: 4,
+    minClicks: 2,
+    maxClicks: 6,
+    lang: "en",
+    canSkip: 1,
+    // pingback: '123.123.123.123' /* More info about pingback https://2captcha.com/setting/pingback */
+    // previousId: '123456789'
+  })  
+  .then((res) => {
+    console.log(res);
+  })
+  .catch((err) => {
+    console.log(err);
+  });

examples/grid_options.js

@@ -4,6 +4,7 @@ import * as utils from "../utils/generic"
 import  getProviderData  from "./providers/providers"
 import { softId } from "./constants/constants"
 import checkCaptchaParams from "../utils/checkCaptchaParams"
+import renameParams from "../utils/renameParams"
 
 
 const provider = getProviderData ()
@@ -44,15 +45,15 @@ export interface paramsHCaptcha {
 
 // FixMe:data[key] - how to send this parameter
 export interface paramsFunCaptcha {
-  publickey: string,
-  pageurl: string,
-  surl?: string,
-  header_acao?: boolean,
-  pingback?: string,
-  proxy?: string,
-  proxytype?: string,
-  userAgent?: string,
-  data?: string
+    publickey: string,
+    pageurl: string,
+    surl?: string,
+    header_acao?: boolean,
+    pingback?: string,
+    proxy?: string,
+    proxytype?: string,
+    userAgent?: string,
+    data?: string
 }
 
 export interface paramsImageCaptcha {
@@ -221,6 +222,21 @@ export interface paramsBoundingBox {
     imginstructions?: string,
 }
 
+export interface paramsGrid {
+    body: string,
+    recaptcha: 1,
+    rows?: number
+    cols?: number
+    minСlicks?: number,
+    maxСlicks?: number,
+    previousId?: string,
+    textinstructions?: string,
+    imginstructions?: string,
+    canSkip?: number,
+    lang?: string,
+    pingback?: string,
+}
+
 /**
  * An object containing properties of the captcha solution.
  * @typedef {Object} CaptchaAnswer
@@ -398,7 +414,7 @@ export class Solver {
     }
 
     /**
-     * Solves a hCaptcha, returning the result as a string.
+     * ### Solves a hCaptcha
      * 
      * [Read more about other hCaptcha parameters](https://2captcha.com/2captcha-api#solving_hcaptcha).
      * 
@@ -452,7 +468,9 @@ export class Solver {
     }
 
     /**
-     * Solves a GeeTest Captcha. [Read more about parameters and solving for Geetest captcha](https://2captcha.com/2captcha-api#solving_geetest).
+     * ### Solves a GeeTest Captcha.
+     * 
+     * [Read more about parameters and solving for Geetest captcha](https://2captcha.com/2captcha-api#solving_geetest).
      * 
      * @param {{ gt, challenge, api_server, offline, new_captcha,
      *  pageurl, pingback, proxy, proxytype, userAgent }} params
@@ -529,7 +547,6 @@ export class Solver {
     /**
      * ### Solves a GeeTest V4 Captcha.
      * 
-     * 
      * This method accepts an object with the following fields: `pageurl`, `captcha_id`, `pingback`, `proxy`, `proxytype`, `userAgent`.
      * The `pageurl` and `captcha_id` fields are required.
      * 
@@ -581,7 +598,8 @@ export class Solver {
     }
 
     /**
-     * Method for sending Yandex Smart Captcha.
+     * ### Method for sending Yandex Smart Captcha.
+     * 
      * This method accepts an object with the following fields: `pageurl`, `sitekey`, `pingback`, `proxy`, `proxytype`.
      * The `pageurl` and `sitekey` fields are required.
      * 
@@ -633,7 +651,9 @@ export class Solver {
 }
 
     /**
-     * Solves a image-based captcha. [Read more about parameters for image captcha](https://2captcha.com/2captcha-api#solving_normal_captcha).
+     * ### Solves a image-based captcha. 
+     * 
+     * [Read more about parameters for image captcha](https://2captcha.com/2captcha-api#solving_normal_captcha).
      * 
      * @param {{ body,
      *           phrase,
@@ -984,17 +1004,6 @@ export class Solver {
         }
     }
 
-    /**
-     *     pageurl: string,
-    captchakey: string,
-    api_server?: string,
-    version?: string,
-    header_acao?: boolean,
-    pingback?: string,
-    proxy?: string,
-    proxytype?: string,
-     */
-
     /**
      * ### Solves Capy Puzzle captcha
      * 
@@ -1342,6 +1351,72 @@ public async boundingBox(params: paramsBoundingBox): Promise<CaptchaAnswer> {
     }
 }
 
+
+/**
+ * ### Grid method
+ * 
+ * The method can be used to bypass tasks where a grid is applied to an image and you need to click on grid tiles, like reCAPTCHA or hCaptcha images.
+ * 
+ * @param {{ body, textinstructions, imginstructions, rows, cols, minСlicks, maxСlicks, previousId, canSkip, lang, pingback}} params Parameters Grid Method as an object.
+ * @param {string} params.body `Base64`- encoded captcha image.
+ * @param {string} params.textinstructions Text will be shown to worker to help him to select object on the image correctly. For example: "*Select cars in the image*". **Optional parameter**, if the instruction already exists in the form of the `imginstructions`. 
+ * @param {string} params.imginstructions Image with instruction for worker to help him to select object on the image correctly. The image must be encoded in `Base64` format. **Optional parameter**, if the instruction already exists in the form of the `textinstructions`.
+ * @param {number} params.rows Number of rows in grid captcha.
+ * @param {number} params.cols Number of columns in grid captcdha.
+ * @param {number} params.minСlicks The minimum number of tiles that must be selected. Can't be more than `rows` * `cols`.
+ * @param {number} params.maxСlicks The maximum number of tiles that can be selected on the image.
+ * @param {string} params.previousId Id of your previous request with the same captcha challenge.
+ * @param {number} params.canSkip Set the value to `1` only if it's possible that there's no images matching to the instruction. We'll provide a button "No matching images" to worker and you will receive `No_matching_images` as answer.
+ * @param {string} params.lang Language code. [See the list of supported languages](https://2captcha.com/2captcha-api#language).
+ * @param {string} params.pingback params.pingback URL for pingback (callback) response that will be sent when captcha is solved. URL should be registered on the server. [More info here](https://2captcha.com/2captcha-api#pingback).
+ * 
+ * @example
+ * solver.grid({
+ *  body: 'iVBORw0KGgoAAAANSUhEUgAAAcIA...',
+ *  textinstructions: "Select cars in the image",
+ *  imginstructions: '/9j/4AAQSkZJRgABAQEA...'
+ * })
+ * .then((res) => {
+ *   console.log(res);
+ *  })
+ * .catch((err) => {
+ *   console.log(err);
+ * })
+ */
+public async grid(params: paramsGrid): Promise<CaptchaAnswer> {
+    checkCaptchaParams(params, "grid")
+
+    params = await renameParams(params)
+
+    const payload = {
+        ...params,
+        method: "base64",
+        recaptcha: 1,
+        ...this.defaultPayload,
+    }
+
+    const URL = this.in
+    const response = await fetch(URL, {
+        body: JSON.stringify( payload ),
+        method: "post",
+        headers: {'Content-Type': 'application/json'}
+    })
+    const result = await response.text()
+
+    let data;
+    try {
+        data = JSON.parse(result)
+    } catch {
+        throw new APIError(result)
+    }
+
+    if (data.status == 1) {
+        return this.pollResponse(data.request)
+    } else {
+        throw new APIError(data.request)
+    }
+}
+
     /**
      * Reports a captcha as correctly solved.
      *