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

| Name | Type | Description | | --- | --- | --- | | token | any | The token given in the constructor, formatted according to whether it is a wolke token or not | | toph | Toph | The Toph class - gives access to toph methods | | korra | Korra | The Korra class - gives access to korra methods | | shimakaze | Shimakaze | The Shimakaze class - gives access to shimakaze methods | | tama | Tama | The Tama class - gives access to tama methods | | images | Toph | Equivalent for toph | | imageGeneration | Korra | Equivalent for korra | | reputation | Shimakaze | Equivalent for reputation | | settings | Tama | Equivalent for tama |

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

Taihou.Taihou

Kind: static class of Taihou

new Taihou(token, wolken, options)

Creates an instance of Taihou.

| Param | Type | Description | | --- | --- | --- | | token | string | The token, required to use weeb.sh | | wolken | boolean | A boolean representing whether the token is a wolke token or not, needed for taihou to work properly | | options | TaihouOptions | An object of options |

TaihouOptions

Kind: global typedef Properties

| Name | Type | Description | | --- | --- | --- | | baseURL | string | The base URL to use for each request, you may change this if you want to use staging or if you run a local instance (like: 'https://api.weeb.sh') | | userAgent | string | Strongly recommended, this should follow a BotName/Version/Environment pattern, or at least the bot name | | timeout | number | Time in milliseconds before a request should be aborted | | headers | any | An object of additional headers following a {'header': 'value'} format, note that those must not be content-type, user-agent or authorization header |

Typedefs

Toph

Kind: global class Properties

| Name | Type | Description | | --- | --- | --- | | token | any | The token given in the constructor of Taihou, formatted according to whether it is a wolke token or not | | options | any | The effective options; e.g, if you specified options specific to Toph, those override the base ones |

• 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

| Param | Type | Default | Description | | --- | --- | --- | --- | | [options] | TophOptions | {} | An optional object of options |

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

| Param | Type | Default | Description | | --- | --- | --- | --- | | uploadOptions | UploadOptions | | An object of options | | [options] | TophOptions | {} | |

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

| Param | Type | Default | Description | | --- | --- | --- | --- | | type | string | | The type, either this or options.tags is mandatory. To get a list of types, use getImageTypes, as well as getImageTags for a list of tags | | [options] | TophOptions | {} | |

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

| Param | Type | Default | | --- | --- | --- | | [options] | TophOptions | {} |

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

| Param | Type | Default | | --- | --- | --- | | [options] | TophOptions | {} |

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

| Param | Type | Default | Description | | --- | --- | --- | --- | | id | string | | The ID of the image to get info from | | [options] | TophOptions | {} | |

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

| Param | Type | Default | Description | | --- | --- | --- | --- | | id | string | | The ID of the image to add tags to | | tags | array | | An array of tags, either strings or {name: 'tag_name'} objects | | [options] | TophOptions | {} | |

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

| Param | Type | Default | Description | | --- | --- | --- | --- | | id | string | | The ID of the image to remove tags from | | tags | array | | An array of tags, either strings or {name: 'tag_name'} objects | | [options] | TophOptions | {} | |

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

| Param | Type | Default | Description | | --- | --- | --- | --- | | id | string | | The ID of the image to remove tags from | | [options] | TophOptions | {} | |

Example

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

TophOptions

Kind: global typedef Properties

| Name | Type | Description | | --- | --- | --- | | baseURL | string | The base URL | | timeout | number | Time in milliseconds before the request should be aborted. Default is 15000 | | headers | any | An object of additional headers following a {'header': 'value'} format, note that those must not be content-type, user-agent or authorization header | | nsfw | boolean | Either a boolean or "only", false entirely filters nsfw, true gets both nsfw and non-nsfw, and "only" gets only nsfw. False by default | | hidden | boolean | If true, you only get back hidden images you uploaded. Defaults to false | | preview | boolean | Only apply to getImageTypes(), if true, a preview image image is sent along. Defaults to false | | fileType | string | Only apply to getRandomImage(), can be "jpeg", "gif" or "png" | | tags | string | Only apply to getRandomImage(), a comma-separated list of tags the image should have | | burst | boolean | Whether to enable the request handler's burst mode, false by default | | beforeNextRequest | number | Only apply per-request, time in milliseconds before the next request in the queue should be executed. Is ignored if burst mode is enabled | | requestsPerMinute | number | Only apply when instantiating the module, regardless of the mode, define how many requests can be done in a minute. 0 makes it limitless |

UploadOptions

Kind: global typedef Properties

| Name | Type | Description | | --- | --- | --- | | file | string | Absolute path to a file, takes priority over url argument | | url | string | Url pointing directly at the image you want to upload, you may only use file or url | | baseType | string | The type of the image; e.g, the category (pat, cuddle and such) | | hidden | boolean | Whether the uploaded image should be private or not | | nsfw | boolean | Whether this image has content that could be considered NSFW (not safe for work) | | tags | string | Comma-separated list of tags to add to the image, they will inherit the hidden property of the image | | source | string | Url pointing to the original source of the image |

Typedefs

Korra

Kind: global class Properties

| Name | Type | Description | | --- | --- | --- | | token | any | The token given in the constructor of Taihou, formatted according to whether it is a wolke token or not | | options | any | The effective options; e.g, if you specified options specific to Korra, those override the base ones |

• 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

| Param | Type | Default | Description | | --- | --- | --- | --- | | [options] | KorraOptions | {} | An optional object of options |

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

| Param | Type | Default | Description | | --- | --- | --- | --- | | type | string | | One of the available types, you can see them here: https://docs.weeb.sh/#generate-simple | | [simpleOptions] | SimpleOptions | | An object of options for this generation, for a complete list of options you can use, check: https://docs.weeb.sh/#generate-simple | | [options] | KorraOptions | {} | |

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

| Param | Type | Default | Description | | --- | --- | --- | --- | | status | string | | The status, can be either "online", "idle", "streaming", "dnd" or "offline" | | avatar | string | | The direct URL to the image | | [options] | KorraOptions | {} | |

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

| Param | Type | Default | Description | | --- | --- | --- | --- | | avatar | string | | The direct URL to the image | | [options] | KorraOptions | {} | |

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

| Param | Type | Default | Description | | --- | --- | --- | --- | | firstTarget | string | | The direct URL to the image of the first target | | secondTarget | string | | The direct URL to the image of the second target | | [options] | KorraOptions | {} | |

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

| Param | Type | Default | | --- | --- | --- | | licenseOptions | LicenseOptions | | | [options] | KorraOptions | {} |

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

| Name | Type | Description | | --- | --- | --- | | baseURL | string | The base URL | | timeout | number | Time in milliseconds before the request should be aborted. Default is 15000 | | headers | any | An object of additional headers following a {'header': 'value'} format, note that those must not be content-type, user-agent or authorization header | | burst | boolean | Whether to enable the request handler's burst mode, false by default | | beforeNextRequest | number | Only apply per-request, time in milliseconds before the next request in the queue should be executed. Is ignored if burst mode is enabled | | requestsPerMinute | number | Only apply when instantiating the module, regardless of the mode, define how many requests can be done in a minute. 0 makes it limitless |

LicenseOptions

Kind: global typedef Properties

| Name | Type | Description | | --- | --- | --- | | title | string | The base URL | | avatar | string | Direct URL to an image | | [badges] | array | Array of http/s links directly pointing to images; to see how it renders, check https://docs.weeb.sh/#license-generation | | [widgets] | array | An array of strings to fill the boxes |

SimpleOptions

Kind: global typedef Properties

| Name | Type | Description | | --- | --- | --- | | [face] | string | Only for awooo type; HEX color code of the face | | [hair] | string | Only for awooo type; HEX color code of the hairs |

Typedefs

Shimakaze

Kind: global class Properties

| Name | Type | Description | | --- | --- | --- | | token | any | The token given in the constructor of Taihou, formatted according to whether it is a wolke token or not | | options | any | The effective options; e.g, if you specified options specific to Shimakaze, those override the base ones |

• 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

| Param | Type | Default | Description | | --- | --- | --- | --- | | [options] | ShimakazeOptions | {} | An optional object of options |

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

| Param | Type | Default | Description | | --- | --- | --- | --- | | botID | string | | The ID of the bot reputation database to access | | targetID | string | | The ID of the user to get reputation of | | [options] | ShimakazeOptions | {} | |

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

| Param | Type | Default | Description | | --- | --- | --- | --- | | reputationOptions | GiveReputationOptions | | An object of options | | [options] | ShimakazeOptions | {} | |

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

| Param | Type | Default | Description | | --- | --- | --- | --- | | resetOptions | ResetUserReputationOptions | | An object of options | | [options] | ShimakazeOptions | {} | |

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

| Param | Type | Default | Description | | --- | --- | --- | --- | | increaseOptions | IncreaseUserReputationOptions | | An object of options | | [options] | ShimakazeOptions | {} | |

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

| Param | Type | Default | Description | | --- | --- | --- | --- | | decreaseOptions | DecreaseUserReputationOptions | | An object of options | | [options] | ShimakazeOptions | {} | |

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

| Param | Type | Default | | --- | --- | --- | | [options] | ShimakazeOptions | {} |

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

| Param | Type | Default | Description | | --- | --- | --- | --- | | settings | ReputationSettings | | The settings to update | | [options] | ShimakazeOptions | {} | |

Example

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

ShimakazeOptions

Kind: global typedef Properties

| Name | Type | Description | | --- | --- | --- | | baseURL | string | The base URL | | timeout | number | Time in milliseconds before the request should be aborted | | headers | any | An object of additional headers following a {'header': 'value'} format, note that those must not be content-type, user-agent or authorization header | | burst | boolean | Whether to enable the request handler's burst mode, false by default | | beforeNextRequest | number | Only apply per-request, time in milliseconds before the next request in the queue should be executed. Is ignored if burst mode is enabled | | requestsPerMinute | number | Only apply when instantiating the module, regardless of the mode, define how many requests can be done in a minute. 0 makes it limitless | | botID | string | - The ID of the bot reputation database to access, if you specify it here, you won't need to specify it in every methods. You can always override it by specifying it in the method, note that methods which don't take objects as argument (methods with 2 or fewer parameters) will take the passed arguments count; As in, if the method expect at least 2 arguments (the bot id and something else) and you pass only one argument, it will be assumed that you want to use the botID set in the constructor |

GiveReputationOptions

Kind: global typedef Properties

| Name | Type | Description | | --- | --- | --- | | botID | string | The ID of the bot reputation database to use | | targetID | string | The ID of the user to give reputation to | | sourceID | string | The ID of the user who is giving reputation |

ResetUserReputationOptions

Kind: global typedef Properties

| Name | Type | Default | Description | | --- | --- | --- | --- | | botID | string | | The ID of the bot reputation database to use | | targetID | string | | The ID of the user to reset | | [resetCooldown] | boolean | false | Whether to reset the user cooldown field too, false by default |

IncreaseUserReputationOptions

Kind: global typedef Properties

| Name | Type | Description | | --- | --- | --- | | botID | string | The ID of the bot reputation database to use | | targetID | string | The ID of the user to reset | | increase | number | By how much should the user reputation be increased |

DecreaseUserReputationOptions

Kind: global typedef Properties

| Name | Type | Description | | --- | --- | --- | | botID | string | The ID of the bot reputation database to use | | targetID | string | The ID of the user to reset | | decrease | number | By how much should the user reputation be decreased |

ReputationSettings

Kind: global typedef Properties

| Name | Type | Description | | --- | --- | --- | | [reputationPerDay] | number | The maximum reputation a user can give per reputationCooldown (so per day by default) | | [maximumReputation] | number | The maximum reputation a user can ever have (there is no maximum by default) | | [maximumReputationReceivedDay] | number | How much reputation a user can receive per day (there is no maximum by default) | | [reputationCooldown] | number | Cooldown per reputation, this is set to time in seconds (must be >= 300) |

Typedefs

Tama

Kind: global class Properties

| Name | Type | Description | | --- | --- | --- | | token | any | The token given in the constructor of Taihou, formatted according to whether it is a wolke token or not | | options | any | The effective options; e.g, if you specified options specific to Tama, those override the base ones | | settingsCache | Collection | The settings cache | | subSettingsCache | Collection | The sub-settings cache |

• 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

| Param | Type | Default | Description | | --- | --- | --- | --- | | [options] | TamaOptions | {} | An optional object of options |

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

| Param | Type | Default | Description | | --- | --- | --- | --- | | type | string | | The type of the setting | | id | string | number | | The ID of the setting | | [options] | TamaOptions | {} | |

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

| Param | Type | Default | Description | | --- | --- | --- | --- | | createOptions | CreateOrUpdateOptions | | An object of parameters | | [options] | TamaOptions | {} | |

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

| Param | Type | Default | Description | | --- | --- | --- | --- | | updateOptions | CreateOrUpdateOptions | | An object of parameters | | [options] | TamaOptions | {} | |

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

| Param | Type | Default | Description | | --- | --- | --- | --- | | type | string | | The type of the setting | | id | string | number | | The ID of the setting | | [options] | TamaOptions | {} | |

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

| Param | Type | Default | Description | | --- | --- | --- | --- | | listOptions | listSubSettingsOptions | | An object of parameters | | [options] | TamaOptions | {} | |

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

| Param | Type | Default | Description | | --- | --- | --- | --- | | getSubSettingOptions | GetSubSettingOptions | | An object of parameters | | [options] | TamaOptions | {} | |

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

| Param | Type | Default | Description | | --- | --- | --- | --- | | createOptions | CreateOrUpdateSubSettingOptions | | An object of parameters | | [options] | TamaOptions | {} | |

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

| Param | Type | Default | Description | | --- | --- | --- | --- | | updateOptions | CreateOrUpdateSubSettingOptions | | An object of parameters | | [options] | TamaOptions | {} | |

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

| Param | Type | Default | Description | | --- | --- | --- | --- | | deleteOptions | DeleteSubSettingOptions | | An object of parameters | | [options] | TamaOptions | {} | |

Example

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

TamaOptions

Kind: global typedef Properties

| Name | Type | Description | | --- | --- | --- | | baseURL | string | The base URL | | timeout | number | Time in milliseconds before the request should be aborted | | headers | any | An object of additional headers following a {'header': 'value'} format, note that those must not be content-type, user-agent or authorization header | | burst | boolean | Whether to enable the request handler's burst mode, false by default | | beforeNextRequest | number | Only apply per-request, time in milliseconds before the next request in the queue should be executed. Is ignored if burst mode is enabled | | requestsPerMinute | number | Only apply when instantiating the module, regardless of the mode, define how many requests can be done in a minute. 0 makes it limitless | | useCache | boolean | Defaults to true, this define whether to use the cache rather than always requesting to weeb.sh. The cache is updated whenever the setting is updated through Taihou |

CreateOrUpdateOptions

Kind: global typedef Properties

| Name | Type | Description | | --- | --- | --- | | type | string | The type of the setting | | id | string | number | The id of the setting | | data | any | The data you want this setting to hold. Please note that existing data will be overriden by this, so in the case of an update, specify unchanged fields too |

listSubSettingsOptions

Kind: global typedef Properties

| Name | Type | Description | | --- | --- | --- | | type | string | The type of the setting | | id | string | number | The id of the setting | | subType | string | The type of the sub-setting |

getSubSettingOptions

Kind: global typedef Properties

| Name | Type | Description | | --- | --- | --- | | type | string | The type of the setting | | id | string | number | The id of the setting | | subType | string | The type of the sub-setting | | subId | string | number | The id of the sub-setting |

CreateOrUpdateSubSettingOptions

Kind: global typedef Properties

| Name | Type | Description | | --- | --- | --- | | type | string | The type of the setting | | id | string | number | The id of the setting | | subType | string | The type of the sub-setting | | subId | string | number | The id of the sub-setting | | data | any | The data you want this sub-setting to hold. Please note that existing data will be overriden by this, so in the case of an update, specify unchanged fields too |

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.