nhentai-tools/lib/index.d.ts

A toolset to interact with the doujin site nhentai.net

export type SortType = 'recent' | 'popular-today' | 'popular-week' | 'popular-month' | 'popular'
export type ImageType = 'j' | 'p' | 'g'
export type TagType = 'artist' | 'character' | 'group' | 'language' | 'parody' | 'tag' | 'category'

/**
 * options for search functions
 * @interface SearchOptions
 * @prop {number}   [page=1]    - page number
 * @prop {SortType} [sort=recent] - sort type
 */
export interface SearchOptions {
    page?: number
    sort?: SortType
}
/**
 * nhentai's search return
 * @interface InternalSearchResult
 * @prop {InternalGallery[]} results   - 0-25 galleries
 * @prop {number}            num_pages - total number of possible search pages
 * @prop {number}            per_page  - total number of search results on the current page
 */
export interface InternalSearchResult {
    result: InternalGallery[]
    num_pages: number
    per_page: number
}
/**
 * nhentai's autocomplete return
 * @interface InternalAutocompleteResult
 * @prop {InternalTag[]} results - array of tags
 */
export interface InternalAutocompleteResult {
    result: InternalTag[]
}
/**
 * nhentai's tag struct
 * @interface InternalTag
 * @prop {number}  id    - tag id
 * @prop {string}  name  - tag name
 * @prop {TagType} type  - tag type
 * @prop {string}  count - tag count
 * @prop {string}  url   - tag url
 */
export interface InternalTag {
    id:    number
    name:  string
    type:  TagType
    count: number
    url:   string
}
/**
 * nhentai's user struct
 * @interface InternalUser
 * @prop {number}  id           - user id
 * @prop {string}  username     - user name
 * @prop {string}  slug         - username formatted for url
 * @prop {string}  avatar_url   - user avatar url
 * @prop {boolean} is_superuser - user is superuser
 * @prop {boolean} is_staff     - user is staff
 */
export interface InternalUser {
    id:           number
    username:     string
    slug:         string
    avatar_url:   string
    is_superuser: boolean
    is_staff:     boolean
}
/**
 * nhentai's comment struct
 * @interface InternalComment
 * @prop {number}       id         - comment id
 * @prop {number}       gallery_id - gallery id
 * @prop {InternalUser} poster     - user id
 * @prop {number}       post_date  - comment creation date
 * @prop {string}       body       - comment content
 */
export interface InternalComment {
    id:         number
    gallery_id: number
    poster:     InternalUser
    post_date:  number
    body:       string
}
/**
 * nhentai's image struct
 * @interface InternalImage
 * @prop {ImageType} t - image type
 * @prop {number}    w - image width
 * @prop {number}    h - image height
 */
export interface InternalImage {
    t: ImageType
    w: number
    h: number
}
/**
 * as much data as can be scraped from a gallery preview
 * @interface InternalGalleryPreview
 * @prop {number}   id       - gallery id
 * @prop {number}   media_id - media id
 * @prop {string}   title    - gallery title
 * @prop {number[]} tag_ids  - gallery tag ids
 */
export interface InternalGalleryPreview {
    id:       number
    media_id: number
    title:    string
    tag_ids:  number[]
}
/**
 * the return from favoriting a gallery
 * @interface InternalFavoriteResult
 * @prop {boolean} favorited     - whether or not the gallery was favorited
 * @prop {number}  num_favorites - the total count of the gallery's favorites after favoriting
 */
export interface InternalFavoriteResult {
    favorited: boolean
    num_favorites: number
}
/**
 * the return from blacklisting a gallery
 * @interface InternalBlacklistResult
 * @prop {string} status - the status of the blacklisting?
 */
export interface InternalBlacklistResult { status: 'ok' }

/**
 * nhentai's gallery struct
 * @interface InternalGallery
 * @prop {number}   id             - gallery id
 * @prop {number}   media_id       - media id
//  * @prop {string}   title           - gallery title
//  * @prop {InternalImage[]} images   - gallery images
 * @prop {string} scanlator        - gallery scanlator (seems to always be blank)
 * @prop {number} upload_date      - gallery upload date
 * @prop {InternalTag[]} tags      - gallery tags
 * @prop {number}  num_pages       - gallery number of pages
 * @prop {number}  num_favorites   - gallery number of favorites 
 */
export interface InternalGallery {
    id:       number
    media_id: number
    title: {
        english:  string
        japanese: string
        pretty:   string
    }
    images: {
        pages:     InternalImage[]
        cover:     InternalImage
        thumbnail: InternalImage
    }
    scanlator:     ''
    upload_date:   number
    tags:          InternalTag[]
    num_pages:     number
    num_favorites: number
}

type _gallery = typeof import('./components/gallery')
/** Functions to interact with singular galleries. */
export const gallery: {
    exists:  _gallery['exists']
    get:     _gallery['get']
    random:  _gallery['random']
    related: _gallery['related']
}

type _comments = typeof import('./components/comments')
/** Functions to interact with comments. */
export const comments: {
    get:    _comments['get']
    submit: _comments['submit']
    remove: _comments['remove']
    flag:   _comments['flag']
}

type _search = typeof import('./components/search')
/** Functions to interact with search. */
export const search: {
    query:        _search['query']
    tagged:       _search['tagged']
    autocomplete: _search['autocomplete']
    homepage:     _search['homepage']
    recent:       _search['recent']
    popular:      _search['popular']
}

type _user = typeof import('./components/user')
/** Functions to interact with a user. */
export const user: {
    readonly isLoggedIn: _user['isLoggedIn']
    getUser:             _user['getUser']
    updateUser:          _user['updateUser']
    login:               _user['login']
    logout:              _user['logout']
    getCaptcha:          _user['getCaptcha']
}

type _favorites = typeof import('./components/favorites')
/** Functions to interact with favorites. */
export const favorites: {
    get:    _favorites['get']
    add:    _favorites['add']
    remove: _favorites['remove']
    random: _favorites['random']
}

type _blacklist = typeof import('./components/blacklist')
/** Functions to interact with a user's blacklist. */
export const blacklist: {
    get:        _blacklist['get']
    change:     _blacklist['change']
    add:        _blacklist['add']
    addMany:    _blacklist['addMany']
    remove:     _blacklist['remove']
    removeMany: _blacklist['removeMany']
}

type _client = typeof import('./components/client')
/** Functions to interact with the internal web requests. */
export const internal: {
    jar: _client['jar']
    client: _client['client']
    preventTooManyRequests: _client['preventTooManyRequests']
    minDelay: _client['minDelay']
}
declare const nhentai: {
    gallery: typeof  gallery,
    comments: typeof comments,
    search: typeof search,
    user: typeof user,
    favorites: typeof favorites,
    blacklist: typeof blacklist,
    internal: typeof internal
}
export default nhentai