The purpose of this library is to provide an interface for logging into ukr.net.
To ensure a seamless experience, it gracefully handles Proof-of-Work tasks, two-factor authentication (2FA), ReCaptcha,
and other mechanisms.
This library is written in TypeScript and supports asynchronous programming. It is also easily extensible through an object-oriented programming (OOP) model.
To start using this library, clone the repository and install the required dependencies using your preferred package manager:
git clone https://github.com/nadvotsky/ukrnet-api.git
cd ukrnet-api/ukrnet-api
yarn installNext, import the main UkrNetAPI class:
import UkrNetAPI from 'ukrnet-api';Then, create a new instance of the class:
const api = new UkrNetAPI();You can pass the following options to customize its behavior:
- Type:
string - Default:
'random' - Description: The User-Agent header used for all requests. If set to
'random', it will be generated using theuser-agentspackage.
-
Type:
string -
Default:
'wasm' -
Description: The name of the Proof-of-Work implementation reported to the server.
-
Values:
'wasm': WASM hint'js': Fallback JavaScript hint
-
Type:
string -
Default:
'random' -
Description: The reported duration of the Proof-of-Work task sent to the server.
-
Values:
'30': Constant value'25-50': Random value in the specified range'random': Default range10-30
- Type:
boolean - Default:
false - Description: Skips the Proof-of-Work task and uses a captcha (not ReCaptcha) instead.
-
Type:
CaptchaProvider -
Default:
undefined -
Description: The captcha solver implementation to use.
-
Values:
TwoCaptchaProvider: Uses the 2Captcha service.CaptchaProvider: A manually implemented provider.
To skip the Proof-of-Work task and solve a captcha instead:
import UkrNetAPI, { TwoCaptchaProvider } from "ukrnet-api";
const api = new UkrNetAPI({
preferCaptchaOverPow: true,
captchaProvider: new TwoCaptchaProvider('<YOUR_API_KEY>'),
});Description: Performs asynchronous initialization of the session, fetching all required parameters for login.
Example:
await api.init();Description:
Sets the password supplier function. PasswordSupplier is a synchronous or asynchronous function that receives the
user login and returns the corresponding password.
This approach avoids storing passwords directly and allows for asynchronous retrieval.
Example:
await api.password(() => 'foobar');Description:
Sets the OTP (One-Time Password) supplier function. OtpSupplier is a synchronous or asynchronous function that
receives the user login and returns the OTP token.
This is optional and only required if two-factor authentication is enabled.
Example:
await api.otp(async (login) => await fetchFromGoogleAuth(login));Description:
Performs a user sign-in with the provided login. Must be called after .init().
The
loginparameter may include or omit@ukr.net— both forms are supported.
Example:
await api.login({ login: 'foo.bar@ukr.net' });Description: Exports the core session parameters as an object (i.e., a "browser session").
Returned structure:
| Property | Type |
|---|---|
sid |
hex |
fvsid |
hex |
freemail |
hex |
Example:
console.log(JSON.stringify(await api.export()));The structure is simple and can be easily serialized to JSON or other formats.
Description: Imports a previously exported session object.
Example:
await api.import(obj);The simplest usage might look like this:
import UkrNetAPI from "ukrnet-api";
import readline from 'readline'; // For interactive OTP input
void async function() {
const api = new UkrNetAPI();
await api
.init()
.then(u => u.password(() => 'foo.bar'))
.then(u => u.otp((): Promise<string> => {
return new Promise((resolve) => {
const rl = readline.createInterface({
input: process.stdin,
output: process.stdout
});
rl.question('OTP code required: ', (code) => {
console.log('Using OTP code:', code);
rl.close();
resolve(code);
});
});
}))
.then(u => u.login({ login: 'test@ukr.net' }));
console.log('Successful login. Session:', JSON.stringify(await api.export()));
}();This project is licensed under the MIT License.