solvemedia.js

An (unofficial) JavaScript wrapper for the SolveMedia API.

Quick example

A quick example as a CLI (which doesn't really make sense, but you get the idea).

require("dotenv").config()
const open = require("open")
const inquirer = require("inquirer")
const { SolveMediaClient } = require("solvemedia.js")
const solvemedia = new SolveMediaClient()

;(async () => {
    await solvemedia.login(process.env.C_KEY, process.env.V_KEY, process.env.H_KEY)
    const challenge = await solvemedia.getChallenge()
    await challenge.writeImageToFile("./captcha.png")
    await open("./captcha.png")
    const { answer } = await inquirer.prompt([{
        name: "answer",
        message: "Type the content of the captcha:"
    }])
    const verified = await challenge.verify(answer)
    console.log(verified ? "Hello, human!" : "Beep boop!" )
})()

Result

This is captcha.png:

This is the CLI itself (running the program twice):

Getting your auth keys

• Register/login at SolveMedia
• If you aren't already there, go to the Portal
• Hover over Configure and click on Sites [?]
• Click on New Site [?]
• Enter whatever you want, and click on Submit
• You should now see your site in the list, click Keys
• Done! You should see a Challenge Key, a Verification Key, and an Authentication Hash Key!

I recommend storing your authorization keys in a .env file and using a library like dotenv, if your project is open source.

Using the image URLs

In SolveMedia, once a client has requested the image of a certain challenge, it will start redirecting following requests to a "media error" image.

This means that once you used, for example Challenge#getImageBuffer(), you won't be able to use Challenge#writeImageToFile() or Challenge#getImageBuffer() again on the same challenge; they will throw a SolveMediaAPIError with error code IMAGE_USED.

SolveMedia also requires for the image URL to be used before verifying it; not doing so will throw a SolveMediaAPIError with error code IMAGE_UNUSED.

API

const { SolveMediaClient, Challenge, SolveMediaAPIError, AuthorizationError } = require("solvemedia.js")

SolveMediaClient

new SolveMediaClient()

login()

Store and validate your SolveMedia credentials.

Parameters

name	description	type	default
challengeKey	Your challenge key	string
verificationKey	Your verification key	string	null
authenticationHashKey	Your authentication hash key	string	null
validate	Whether to validate the given key(s) by requesting a challenge	boolean	true

Returns

Promise<SolveMediaClient>

getChallenge()

Obtain a challenge/captcha from the SolveMedia API.

Parameters

name	description	type	default
userIP	The user's IP, to increase/decrease the difficulty accordingly	string	null (random IP)

Returns

Promise<Challenge>

Challenge

You probably shouldn't initialize this class manually, use SolveMediaClient#getChallenge() instead.

new Challenge(body, auth, userIP)

Constructor parameters

name	description	type	default
body	Options to personalize the image	string
auth	The client's authorization keys	object
auth.challengeKey	The client's challenge key	string
auth.verificationKey	The client's verification key	string	null
auth.authenticationHashKey	The client's authentication hash key	string	null
userIP	The user's IP	string

verify()

Verify the user's answer. Requires the verification key to be stored.

Parameters

name	description	type	default
answer	The user's answer	string
authenticateResponse	Whether to authenticate SolveMedia's response (requires the authentication hash key)	boolean	true

Returns

Promise<boolean>

getImageURL()

Get the URL of the image.

Parameters

name	description	type	default
options	Options to personalize the image	object	{}
options.width	The width of the image	number	300
options.height	The height of the image	number	150
options.foreground	The foreground color of the image	string	"000000"
options.background	The background color of the image	string	"f8f8f8"

Returns

string

getImageBuffer()

Get the image as a buffer.

Parameters

name	description	type	default
imageOptions	Options to personalize the image, passed to getImageURL()	object	{}

Returns

Promise<Buffer>

writeImageToFile()

Write the image to a file.

Parameters

name	description	type	default
path	The path of the new file	string
imageOptions	Options to personalize the image, passed to getImageURL()	object	{}

Returns

Promise<fs.WriteStream>

SolveMediaAPIError

Thrown when the response from SolveMedia is either invalid, or contains an error.

new SolveMediaAPIError(code, unknownErrorMessage)

Constructor parameters

name	description	type	default
code	The error code	string
unknownErrorMessage	The SM error message to format the "UNKNOWN_ERROR" message	string	null

code

The error code.

The possible error codes are:

• UNKNOWN_ERROR: Unknown error: {...}
• JSON_INVALID: Response body is not valid JSON.
• BODY_INCOMPLETE: Response body does not contain the necessary values.
• IMAGE_UNUSED: The image URL has to be used before verifying an answer.
• IMAGE_USED: The image URL has already been used.
• IP_INVALID: Invalid IP address.
• CHALLENGE_ALREADY_VERIFIED: This challenge has already been verified.
• CHALLENGE_INVALID: Invalid challenge ID.
• CHALLENGE_EXPIRED: This challenge has expired.

Type

string

message

The error message.

Type

string

AuthorizationError (extends SolveMediaAPIError)

Thrown when the provided credentials are invalid or unavailable to the client.

new SolveMediaAPIError(code, unknownErrorMessage)

Constructor parameters

name	description	type	default
code	The error code	string

code

The error code.

The possible error codes are:

• AUTH_MISSING: Credentials are unavailable.
• CKEY_MISSING: Challenge key is unavailable.
• CKEY_INVALID: Invalid challenge key.
• VKEY_MISSING: Verification key is unavailable.
• VKEY_INVALID: Invalid verification key.
• HKEY_MISSING: Authentication hash key is unavailable.
• RESPONSE_NOT_AUTHENTIC: The response is not authentic, or the authentication hash key is invalid.

Type

string