nhentai-tools/README.md

A toolset to interact with the doujin site nhentai.net

<div align="center">
    <h1>nhentai tools</h1>
    <i>a degenerate's work</i></br></br>
    <a href="disclaimers">Disclaimers</a>
    ·
    <a href="#installation">Installation</a>
    ·
    <a href="#api">API</a>
    ·
    <a href="#examples">Examples</a>
    ·
    <a href="#dependencies">Dependencies</a>
</div>
</br>

In my long, sad walks of the web, I've realized that most every package interacting with the doujin site [nhentai.net](https://nhentai.net) is a simple scraper, despite an <i>official</i> (but entirely undocumented) api at [nhentai.net/api](https://nhentai.net/api).

This package was created to bring awareness to this api and to make it exceedingly easy to create simple projects interacting with [nhentai](https://nhentai.net).

## Disclaimers
I am currently a student, so updates will be neither regular, nor high quality. This has been developed as a result of too many long nights, so code might just not work at all. If there's a problem, leave an issue describing what causes it and I'll try to fix it soon.

Secondly, nhentai has a scuffed website, and an even more scuffed api. It's not that they don't work, they just don't work quite right. Occasionally searching by `recent` will return `{ error: true }`, on the second login in a short time a captcha will be required, but cannot be used, etc. I'm working to make these errors not affect users/developers, but there's always unexpected behavior. If you find a reproducable issue, create a pull request if you can find a way to fix it, or an issue if you can't.

## Installation
- With [npm](https://www.npmjs.com):
```sh
npm install nhentai-tools
```
- With [pnpm](https://pnpm.io):
```sh
pnpm add nhentai-tools
```

## Examples
- Check if a doujin exists:
```js
import nhentai from 'nhentai-tools';

nhentai.gallery.exists(383446)
    .then(exists => {
        // expected output: doujin 383446 exists.
        console.log(`doujin 383446 ${exists ? 'exists' : 'does not exist'}.`);
    })
```
- Get a specific doujin:
```js
import nhentai from 'nhentai-tools';

// get the doujin at https://nhentai.net/g/383300
nhentai.gallery.get(383300)
    .then(gallery => {
        // expected output: title: Kosho ni Umoreta Mesu no Hana | A Bitch Rose Shrouded in Books
        console.log(`title: ${gallery.title.pretty}`);
        // expected output: id: 383300
        console.log(`id: ${gallery.id}`);
    })
```
- Get a random doujin:
```js
import nhentai from 'nhentai-tools';

// get the doujin at https://nhentai.net/random
nhentai.gallery.random()
    .then(id => {
        // get the gallery data for the id
        return nhentai.gallery.get(id);
    })
    .then(randomGallery => {
        // expected output: {english: '...', japanese: '...', pretty: '...'}
        console.log(randomGallery.title);
        // expected output: id: ...
        console.log(randomGallery.id);
    })
```
- Search for a query:
```js
import nhentai from 'nhentai-tools';

// search for the tag kemonomimi, then get the second page sorted by popularity in the past month
nhentai.search.query('tag:kemonomimi', { page: 2, sort: 'popular-month' })
    .then(search => {
        // expected output: 416
        console.log(search.num_pages);

        // create galleries
        const galleries = search.result;
        // expected output: length: 25
        console.log(`length: ${galleries.length}`);
    })
```
- Get ALL comments under a specific doujin (for some reason, nhentai's api just sends all of them at once):
```js
import nhentai from 'nhentai-tools';

// get ALL comments under the doujin 177013 (1.58 mb of text lol)
nhentai.comments.get(177013)
    .then(comments => {
        // expected output: 4114
        console.log(comments.length)

        // be very careful when simply looping through comments
        // as the array can often be over 1000 entries long
        for (const comment of comments) {
            // destructure the comment object to extract comment.body and comment.poster.username
            const { poster: { username }, body } = comment
            const postDate = new Date(comment.post_date * 1000)

            console.log(`user '${username}' said '${body}' on ${postDate.toDateString()} at ${postDate.toTimeString()}.`)
        }
    })
```
- Login as a user and interact with favorites (**warning:** requires google chrome for solving captchas):
```js
import nhentai from 'nhentai-tools';

// login as user/pass
nhentai.user.login('user', 'pass')
    .then(() => {
        console.log('logged in!')
        // remove something cursed
        return nhentai.user.favorites.remove(177013)
    })
    .then(() => {
        console.log('removed the cursed gallery')
        // add something less cursed
        return nhentai.user.favorites.add(383300)
    })
    .then(() => {
        console.log('added something good')
    })
    // don't forget to log out after completing all actions
    // or do, all it does is makes your captcha easier
    .finally(() => nhentai.user.logout())
```

## Dependencies
This project requires:
 - [axios]('https://axios-http.com')
    - A wonderful requests library.
    - Used for all web requests in this library.
 - [chrome-launcher]('https://github.com/GoogleChrome/chrome-launcher')
    - A simple library which does exactly what it should.
    - Used to display captchas for logging in and adding comments.
 - [chrome-remote-interface]('https://github.com/cyrus-and/chrome-remote-interface')
    - A library to interact with chrome instances. Works as intended, just hard to find how to do anything.
    - Used to find a captcha key.

## API
The default export exposes:
 - gallery: All methods relating to a gallery, like getting a random id, or getting data from an id.
 - comments: All methods relating to user comments, like submitting or deleting.
 - search: All methods relating to searching nhentai's database.
 - user: All methods relating to a single user.
 - favorites: All methods relating to adding or removing favorites.