taihou v2.0.7

Taihou - A weeb.sh wrapper

Taihou is a promise-returning Node.js wrapper for weeb.sh. Taihou is easy to use but also has a lot of advanced features for a more advanced usage. To get started, you should head over to the requirements and usage sections

Special thanks to MrLar (MrLar 🌺#0611) who helped me getting the Korra wrapper to work

Tables of content

• Features
• Requirements
• Changelog
• Usage

• • Passing options to specific services/methods
• • Sending generated images to Discord
• • • With Eris
• • • With Discord.js

• Documentation

• • Taihou
• • Toph
• • Korra
• • Shimakaze
• • Tama
• • Request handling
• • • Sequential mode
• • • Burst mode
• • • Sequential VS Burst example case
• • Error handling
• • Tama's caching behavior

Features

• Full cover for weeb.sh services
• Consistent interface
• Entirely configurable, with global, per-services and per-requests configuration
• Configurable built-in rate-limiter (see request handling)
• Built-in cache for Tama
• Named after the Imperial Japanese Navy's first armored aircraft carrier, which not only had a funny fate, but has also a cute as hell kancolle equivalent

Requirements

The lowest known Node.js version supported is Node.js 8.3.0

Changelog

Patch 2.0.7

Typings by PapiOphidian

Patch 2.0.6

Another security bump for axios, bumping from 0.21.1 to 0.21.2.

Patch 2.0.5

This patch fixes the methods broken by patch 2.0.4

Security Patch 2.0.4

This patch fixes a security issue within axios by bumping the required axios version from 0.18.1 to 0.21.1.

Important Security Patch 2.0.3

2.0.2 => 2.0.3

This patch fixes a security issue within axios by bumping the required axios version from 0.18.0 to 0.18.1, see the relevant changelog here

Update 2.0.2

1.0.2 => 2.0.2

This update optimize a bit the internal code documentation and document the responses of all methods, which should make any code editor that supports JSDoc able to provide decent Intellisense.

The reason why this is a major update is because of the potentially breaking rework of error handling, rejected/thrown errors are no longer instances of the TaihouError class, but instances of Node.js's Error class. Errors that are directly originating from the request sent to the weeb.sh servers are following Axios's error scheme

Usage

While the size of this readme may make it look complicated, Taihou is fairly easy to use:

npm install taihou

Once installed, to start using Taihou:

const Taihou = require('taihou');
const weebSH = new Taihou('token', true, {
    userAgent: 'YourBotName/YourBotVersion'
});

weebSH.toph.getRandomImage('pat')
    .then(image => console.log(image.url))
    .catch(err => console.error(`Oopsie, an error occurred: ${err}`));

//You can also access the classes with their english name description, like

weebSH.images.getRandomImage('pat')
    .then(image => console.log(image.url))
    .catch(err => console.error(`Oopsie, an error occurred: ${err}`));

//Which is exactly the same

To see all the methods available and the different possibilities, check out the documentation

Passing options to specific services or methods

Some options can be set globally, per-service and per-request, per-service override global, and per-request override per-service options.

const Taihou = require('taihou');
const weebSH = new Taihou('token', true, {
    userAgent: 'YourBotName/YourBotVersion',
    timeout: 15000, //Globally set the maximum time in ms to wait before aborting a request to 15000,
    baseURL: 'https://api.weeb.sh'
    toph: {
        timeout: 5000 //Set 5000ms instead of 15000 for all toph methods,
        baseURL: 'https://staging.weeb.sh' //You can use a different environment for a specific service, and even for a specific request 
    },
    images: {
        timeout: 5000 //If you don't want to use the name "toph", it can be done with "images" too
    }
});

weebSH.toph.getRandomImage('pat', {timeout: 3000}) //Set 3000ms instead of 5000 for this specific request
    .then(image => console.log(image.url))
    .catch(err => console.error(`Oopsie, an error occurred: ${err}`));

Sending generated images to Discord

Especially if it's your first time dealing with buffers, sending the images generated by Korra might be a little confusing. The two examples below show how to do it in the most probable context (when a command is called)

With Eris

weebSH.korra.generateWaifuInsult('https://cdn.discordapp.com/attachments/397069608043020298/452094168890867722/memesie.png') 
    .then(buffer => {
        message.channel.createMessage('', {file: buffer, name: `${Date.now()}-${message.author.id}.png`})
    })
    .catch(err => console.error(`Oopsie, an error occurred: ${err}`));

With Discord.js

weebSH.korra.generateWaifuInsult('https://cdn.discordapp.com/attachments/397069608043020298/452094168890867722/memesie.png') 
    .then(buffer => {
        message.channel.send('', {files: [{attachment: buffer, name: `${Date.now()}-${message.author.id}.png`]})
    })
    .catch(err => console.error(`Oopsie, an error occurred: ${err}`));

Documentation

Typedefs

Taihou

Kind: global class Properties

• Taihou
  • .Taihou
    • new Taihou(token, wolken, options)

Taihou.Taihou

Kind: static class of Taihou

new Taihou(token, wolken, options)

Creates an instance of Taihou.

TaihouOptions

Kind: global typedef Properties

Typedefs

Toph

Kind: global class Properties

• Toph
  • .getStatus([options]) ⇒ Promise.<boolean>
  • .uploadImage(uploadOptions, [options]) ⇒ Promise.<any>
  • .getRandomImage(type, [options]) ⇒ Promise.<any>
  • .getImageTypes([options]) ⇒ Promise.<any>
  • .getImageTags([options]) ⇒ Promise.<any>
  • .getImageInfo(id, [options]) ⇒ Promise.<any>
  • .addTagsToImage(id, tags, [options]) ⇒ Promise.<any>
  • .removeTagsFromImage(id, tags, [options]) ⇒ Promise.<any>
  • .deleteImage(id, [options]) ⇒ Promise.<any>

toph.getStatus(options) ⇒ Promise.<boolean>

Make a simple request to check whether Toph is available or not, due to its nature, this method never rejects

Kind: instance method of Toph Returns: Promise.<boolean> - Whether or not Toph is online

Example

weebSH.toph.getStatus()
    .then(console.log) //true

toph.uploadImage(uploadOptions, options) ⇒ Promise.<any>

Upload an image to Toph

Kind: instance method of Toph Returns: Promise.<any> - An image object with a file key

Example

weebSH.toph.uploadImage({url: 'https://wew.png', type: 'wew', hidden: true, nsfw: false})
    .then(console.log)
    .catch(console.error)

toph.getRandomImage(type, options) ⇒ Promise.<any>

Get a random image from weeb.sh, you can specify both type and options.tags. You can also set the type to null and only specify options.tags

Kind: instance method of Toph Returns: Promise.<any> - The parsed image object, refer to https://docs.weeb.sh/#random-image for its structure

Example

weebSH.toph.getRandomImage('pat')
    .then(console.log)
    .catch(console.error)

toph.getImageTypes(options) ⇒ Promise.<any>

Get a list of image types and a preview image for each if you want

Kind: instance method of Toph Returns: Promise.<any> - The parsed response object that you can see here https://docs.weeb.sh/#image-types

Example

weebSH.toph.getImageTypes()
    .then(console.log)
    .catch(console.error)

toph.getImageTags(options) ⇒ Promise.<any>

Get a list of image tags

Kind: instance method of Toph Returns: Promise.<any> - The parsed response object that you can see here https://docs.weeb.sh/#image-tags

Example

weebSH.toph.getImageTags()
    .then(console.log)
    .catch(console.error)

toph.getImageInfo(id, options) ⇒ Promise.<any>

Get info about an image using its ID

Kind: instance method of Toph Returns: Promise.<any> - The parsed response object that you can see here https://docs.weeb.sh/#image-info

Example

weebSH.toph.getImageInfo('6d875e')
    .then(console.log)
    .catch(console.error)

toph.addTagsToImage(id, tags, options) ⇒ Promise.<any>

Add tags to an image

Kind: instance method of Toph Returns: Promise.<any> - An object detailing added and skipped tags

Example

weebSH.toph.addTagsToImage('6d875e', ['baguette'])
    .then(console.log)
    .catch(console.error)

toph.removeTagsFromImage(id, tags, options) ⇒ Promise.<any>

Remove tags from an image

Kind: instance method of Toph

Example

weebSH.toph.removeTagsFromImage('6d875e',  ['baguette'])
    .then(console.log)
    .catch(console.error)

toph.deleteImage(id, options) ⇒ Promise.<any>

Delete an image

Kind: instance method of Toph Returns: Promise.<any> - An object containing a success confirmation

Example

weebSH.toph.deleteImage('6d875e')
    .then(console.log)
    .catch(console.error)

TophOptions

Kind: global typedef Properties

UploadOptions

Kind: global typedef Properties

Typedefs

Korra

Kind: global class Properties

• Korra
  • .getStatus([options]) ⇒ Promise.<boolean>
  • .generateSimple(type, [simpleOptions], [options]) ⇒ Promise.<any>
  • .generateDiscordStatus(status, avatar, [options]) ⇒ Promise.<any>
  • .generateWaifuInsult(avatar, [options]) ⇒ Promise.<any>
  • .generateLoveShip(firstTarget, secondTarget, [options]) ⇒ Promise.<any>
  • .generateLicense(licenseOptions, [options]) ⇒ Promise.<any>

korra.getStatus(options) ⇒ Promise.<boolean>

Make a simple request to check whether Korra is available or not, due to its nature, this method never rejects

Kind: instance method of Korra Returns: Promise.<boolean> - Whether or not Korra is online

Example

weebSH.korra.getStatus()
    .then(console.log)
    .catch(console.error)

korra.generateSimple(type, simpleOptions, options) ⇒ Promise.<any>

Kind: instance method of Korra Returns: Promise.<Buffer> - The image buffer, that you can directly pass to d.js/eris

Example

weebSH.korra.generateSimple('awooo')
    .then(console.log)
    .catch(console.error)

korra.generateDiscordStatus(status, avatar, options) ⇒ Promise.<any>

Kind: instance method of Korra Returns: Promise.<Buffer> - The image buffer, that you can directly pass to d.js/eris

Example

weebSH.korra.generateDiscordStatus('online', 'https://cdn.discordapp.com/avatars/140149699486154753/a_211d333073a63b3adfd13943268fc7a1.webp?size=1024')
    .then(console.log)
    .catch(console.error)

korra.generateWaifuInsult(avatar, options) ⇒ Promise.<any>

Kind: instance method of Korra Returns: Promise.<Buffer> - The image buffer, that you can directly pass to d.js/eris

Example

weebSH.korra.generateWaifuInsult('https://cdn.discordapp.com/avatars/140149699486154753/a_211d333073a63b3adfd13943268fc7a1.webp?size=1024')
    .then(console.log)
    .catch(console.error)

korra.generateLoveShip(firstTarget, secondTarget, options) ⇒ Promise.<any>

Kind: instance method of Korra Returns: Promise.<Buffer> - The image buffer, that you can directly pass to d.js/eris

Example

weebSH.korra.generateLoveShip('https://cdn.discordapp.com/avatars/128392910574977024/174c3436af3e4857accb4a32e2f9f220.webp?size=1024', 'https://cdn.discordapp.com/avatars/108638204629925888/e05fb8c7720c3618569828246e176fb4.webp?size=1024')
    .then(console.log)
    .catch(console.error)

korra.generateLicense(licenseOptions, options) ⇒ Promise.<any>

Kind: instance method of Korra Returns: Promise.<Buffer> - The image buffer, that you can directly pass to d.js/eris

Example

weebSH.korra.generateLicense({title: 'Baguette License', avatar: 'https://cdn.discordapp.com/avatars/128392910574977024/174c3436af3e4857accb4a32e2f9f220.webp?size=1024'})
    .then(console.log)
    .catch(console.error)     

KorraOptions

Kind: global typedef Properties

LicenseOptions

Kind: global typedef Properties

SimpleOptions

Kind: global typedef Properties

Typedefs

Shimakaze

Kind: global class Properties

• Shimakaze
  • .getStatus([options]) ⇒ boolean
  • .getUserReputation(botID, targetID, [options]) ⇒ Promise.<any>
  • .giveReputation(reputationOptions, [options]) ⇒ Promise.<any>
  • .resetUserReputation(resetOptions, [options]) ⇒ Promise.<any>
  • .increaseUserReputation(increaseOptions, [options]) ⇒ Promise.<any>
  • .decreaseUserReputation(decreaseOptions, [options]) ⇒ Promise.<any>
  • .getSettings([options]) ⇒ Promise.<any>
  • .setSettings(settings, [options]) ⇒ Promise.<any>

shimakaze.getStatus(options) ⇒ boolean

Make a simple request to check whether Shimakaze is available or not, due to its nature, this method never rejects

Kind: instance method of Shimakaze Returns: boolean - Whether or not Shimakaze is online

Example

weebSH.shimakaze.getStatus()
    .then(console.log)
    .catch(console.error)

shimakaze.getUserReputation(botID, targetID, options) ⇒ Promise.<any>

Get the reputation of a user

Kind: instance method of Shimakaze Returns: Promise.<any> - The parsed response object, refer to https://docs.weeb.sh/#get-reputation-of-user for its structure

Example

weebSH.shimakaze.getUserReputation('327144735359762432', '184051394179891201')
    .then(console.log)
    .catch(console.error)

shimakaze.giveReputation(reputationOptions, options) ⇒ Promise.<any>

Give reputation to a user

Kind: instance method of Shimakaze Returns: Promise.<any> - The parsed response object, refer to https://docs.weeb.sh/#get-reputation-of-user for its structure

Example

weebSH.shimakaze.postUserReputation({botID: '184051394179891201', targetID: '128392910574977024', sourceID: '140149699486154753'})
    .then(console.log)
    .catch(console.error)

shimakaze.resetUserReputation(resetOptions, options) ⇒ Promise.<any>

Reset the reputation of a user

Kind: instance method of Shimakaze Returns: Promise.<any> - The parsed response object, refer to https://docs.weeb.sh/#reset-user-reputation for its structure

Example

weebSH.shimakaze.resetUserReputation({botID: '327144735359762432', targetID: '184051394179891201'})
    .then(console.log)
    .catch(console.error)

shimakaze.increaseUserReputation(increaseOptions, options) ⇒ Promise.<any>

Increase the reputation of a user

Kind: instance method of Shimakaze Returns: Promise.<any> - The parsed response object, refer to https://docs.weeb.sh/#increase-user-reputation for its structure

Example

weebSH.shimakaze.increaseUserReputation({botID: '327144735359762432', targetID: '184051394179891201', increase: 1})
    .then(console.log)
    .catch(console.error)

shimakaze.decreaseUserReputation(decreaseOptions, options) ⇒ Promise.<any>

Decrease the reputation of a user

Kind: instance method of Shimakaze Returns: Promise.<any> - The parsed response object, refer to https://docs.weeb.sh/#decrease-user-reputation for its structure

Example

weebSH.shimakaze.decreaseUserReputation({botID: '327144735359762432', targetID: '184051394179891201', decrease: 1})
    .then(console.log)
    .catch(console.error)

shimakaze.getSettings(options) ⇒ Promise.<any>

Get the current settings

Kind: instance method of Shimakaze Returns: Promise.<any> - The parsed response object, refer to https://docs.weeb.sh/#get-settings for its structure

Example

weebSH.shimakaze.getSettings()
    .then(console.log)
    .catch(console.error)

shimakaze.setSettings(settings, options) ⇒ Promise.<any>

Update the current settings

Kind: instance method of Shimakaze Returns: Promise.<any> - The parsed response object, refer to https://docs.weeb.sh/#set-settings for its structure

Example

weebSH.shimakaze.setSettings({reputationPerDay: 3})
    .then(console.log)
    .catch(console.error)

ShimakazeOptions

Kind: global typedef Properties

GiveReputationOptions

Kind: global typedef Properties

ResetUserReputationOptions

Kind: global typedef Properties

IncreaseUserReputationOptions

Kind: global typedef Properties

DecreaseUserReputationOptions

Kind: global typedef Properties

ReputationSettings

Kind: global typedef Properties

Typedefs

Tama

Kind: global class Properties

• Tama
  • .getStatus([options]) ⇒ boolean
  • .getSetting(type, id, [options]) ⇒ Promise.<any>
  • .createSetting(createOptions, [options]) ⇒ Promise.<any>
  • .updateSetting(updateOptions, [options]) ⇒ Promise.<any>
  • .deleteSetting(type, id, [options]) ⇒ Promise.<any>
  • .listSubSettings(listOptions, [options]) ⇒ Promise.<any>
  • .getSubSetting(getSubSettingOptions, [options]) ⇒ Promise.<any>
  • .createSubSetting(createOptions, [options]) ⇒ Promise.<any>
  • .updateSubSetting(updateOptions, [options]) ⇒ Promise.<any>
  • .deleteSubSetting(deleteOptions, [options]) ⇒ Promise.<any>

tama.getStatus(options) ⇒ boolean

Make a simple request to check whether Tama is available or not, due to its nature, this method never rejects

Kind: instance method of Tama Returns: boolean - Whether or not Tama is online

Example

weebSH.tama.getStatus()
    .then(console.log)
    .catch(console.error)

tama.getSetting(type, id, options) ⇒ Promise.<any>

Get a setting by type and ID

Kind: instance method of Tama Returns: Promise.<any> - The parsed response object, with a cached property representing whether the returned setting is from the cache, refer to https://docs.weeb.sh/#get-setting for its structure

Example

weebSH.tama.getSetting('guilds', '300407204987666432')
    .then(console.log)
    .catch(console.error)

tama.createSetting(createOptions, options) ⇒ Promise.<any>

Technically you can update an existing setting with this method too, the only reason there is two different methods is to be clearer

Kind: instance method of Tama Returns: Promise.<any> - The parsed response object, refer to https://docs.weeb.sh/#create-update-setting for its structure

Example

weebSH.tama.createSetting({type: 'guilds', id: '300407204987666432', data: {prefix: 'poi', baguette: true}})
    .then(console.log)
    .catch(console.error)

tama.updateSetting(updateOptions, options) ⇒ Promise.<any>

Technically you can create a setting with this method too, the only reason there is two different methods is to be clearer

Kind: instance method of Tama Returns: Promise.<any> - The parsed response object, refer to https://docs.weeb.sh/#create-update-setting for its structure

Example

weebSH.tama.updateSetting({type: 'guilds', id: '300407204987666432', data: {prefix: 'poi', baguette: false}})
    .then(console.log)
    .catch(console.error)

tama.deleteSetting(type, id, options) ⇒ Promise.<any>

If options.useCache is true, the setting will also be deleted from the cache. Note that this however won't delete the subsettings

Kind: instance method of Tama Returns: Promise.<any> - The parsed response object, refer to https://docs.weeb.sh/#delete-setting for its structure

Example

weebSH.tama.deleteSetting('guilds', '300407204987666432')
    .then(console.log)
    .catch(console.error)

tama.listSubSettings(listOptions, options) ⇒ Promise.<any>

Get a list of sub-settings for a sub-setting type.

Kind: instance method of Tama Returns: Promise.<any> - The parsed response object, refer to https://docs.weeb.sh/#list-sub-settings for its structure

Example

weebSH.tama.listSubSettings({type: 'guilds', id: '300407204987666432', subType: 'channels'})
    .then(console.log)
    .catch(console.error)

tama.getSubSetting(getSubSettingOptions, options) ⇒ Promise.<any>

Get a sub-setting by type and id

Kind: instance method of Tama Returns: Promise.<any> - The parsed response object, along with a cached property representing whether the returned sub-setting is from the cache, refer to https://docs.weeb.sh/#get-sub-settings for its structure

Example

weebSH.tama.getSubSetting({type: 'guilds', id: '300407204987666432', subType: 'channels', subId: '439457506960605185'})
    .then(console.log)
    .catch(console.error)

tama.createSubSetting(createOptions, options) ⇒ Promise.<any>

Technically this method can be used to update a sub-setting too, the only reason there is two different methods is to be clearer

Kind: instance method of Tama Returns: Promise.<any> - The parsed response object, refer to https://docs.weeb.sh/#create-update-sub-setting for its structure

Example

weebSH.tama.createSubSetting({type: 'guilds', id: '300407204987666432', subType: 'channels', subId: '439457506960605185', data: {weeb: false}})
    .then(console.log)
    .catch(console.error)

tama.updateSubSetting(updateOptions, options) ⇒ Promise.<any>

Technically this method can be used to create a sub-setting too, the only reason there is two different methods is to be clearer

Kind: instance method of Tama Returns: Promise.<any> - The parsed response object, refer to https://docs.weeb.sh/#create-update-sub-setting for its structure

Example

weebSH.tama.createSubSetting({type: 'guilds', id: '300407204987666432', subType: 'channels', subId: '439457506960605185', data: {weeb: true}})
    .then(console.log)
    .catch(console.error)

tama.deleteSubSetting(deleteOptions, options) ⇒ Promise.<any>

Delete a sub-setting

Kind: instance method of Tama Returns: Promise.<any> - The parsed response object, refer to https://docs.weeb.sh/#delete-sub-setting for its structure

Example

 weebSH.tama.deleteSubSetting({type: 'guilds', id: '300407204987666432', subType: 'channels', subId: '439457506960605185'})
    .then(console.log)
    .catch(console.error)

TamaOptions

Kind: global typedef Properties

CreateOrUpdateOptions

Kind: global typedef Properties

listSubSettingsOptions

Kind: global typedef Properties

getSubSettingOptions

Kind: global typedef Properties

CreateOrUpdateSubSettingOptions

Kind: global typedef Properties

Request handling

Taihou comes with her own built-in rate-limiter, note that there is no official rate-limits on weeb.sh, the rate-limiter defaults rate-limits are set to what i think is respectful to the API, you are free to adjust the rate-limits to what you think is best or even disable them entirely by setting requestsPerMinutes to 0

Note that, as weeb.sh offer different services (toph, tama...), each service has its own request handler in Taihou, meaning that rate-limits are per-service and not global (so if you hit the limit in toph for example, you can still use tama)

There is a burst option, by default set to false, if true, the request handler will switch from sequential to burst mode, more information about those below.

Sequential mode

The sequential mode, which is the default mode, distribute the load of requests evenly: After each request, it waits 60000 / <requestsPerMinutes> before executing the next request. There is an example case below which shows clearly how it works

If you want to wait longer or shorter after a specific request, you can pass the beforeNextRequest option when calling a method, that will make the request handler wait the specified milliseconds before executing the next request in the queue

Burst mode

The burst mode works pretty much exactly like if there was no rate-limiter, except that there is still a limit. Queued requests will be directly executed, unless it executed as much requests as the limit in the past minute already, in this case, it will wait for the said minute to pass before executing the rest

Sequential VS Burst example case

To see clearly how these two modes acts, we'll take a simple use case:

Let's say there is 61 requests to Korra (image-generation) in the queue. The default rate-limit on Korra is 60 requests/minute

The sequential mode will execute a request/second (60000 / 60 => 1000 milliseconds => 1 second) and therefore will finish executing all the requests after 1 minute and 1 second

The burst mode will execute all requests as fast as it can, (so most likely the first 60 during the first second) but will then hit the limit, and wait for the minute to pass before executing the last one.

Meaning that both modes will execute the 61 requests in the queue in ~1 minute and 1 second

In most cases the sequential mode is more suited, which is why it's the default, but feel free to chose what you think is best

Error handling

Malformed requests errors are instances of Node.js's Error class while errors that are directly originating from the request sent to the weeb.sh servers are following Axios's error scheme

Tama caching behavior

As you can store things such as prefixes with Tama, and that you most likely want to access the said prefixes whenever your bot receive a message, Taihou comes with a enabled by default built-in cache to not spam the API and to serve settings faster.

Whenever you request a setting/subsetting (like with the Tama.getSetting() method for example), the object returned by weeb.sh will be put into the cache, then, when you request the same setting again, the cached one will be returned. You can explicitly tell Taihou to not use the cache by passing the useCache: false option

Not only when you fetch a setting, but also when you create/update a setting/subsetting, the cache will be updated, to ensure that the cached version is always up-to-date. As well as when you delete a setting/sub-setting, it is deleted from the cache as well (unless you specify otherwise, more information below)

A cached property is added to the objects that can potentially be returned from the cache, if true, it means the returned object is from the cache

Though there's still a lot of use cases where the cache might not be welcome, if for example another process (another bot for example) change the settings, the cached version won't be updated, as Taihou is not able to know that. This is why the useCache option is available, you can either set it to false for the entire service, or set it to false for specific requests.

The useCache option gives you great control over the cache, as when you set it to false you, you tell to Taihou "Do not interact with the cache at all" rather than something like "Do not fetch from the cache". Meaning that if you for example request a setting deletion, and that useCache is set to false, the cached version (if any) won't be deleted. Same if you create/update a setting, if useCache is set to false, the setting won't be added/updated in the cache.