Skip to content

ParadoxalCorp/Taihou

BranchesTags

Repository files navigation

Taihou - A weeb.sh wrapper

CircleCI Codacy Badge

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

  • 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

Taihou

Typedefs

TaihouOptions

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

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
Toph

Typedefs

TophOptions
UploadOptions

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>

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
Korra

Typedefs

KorraOptions
LicenseOptions
SimpleOptions

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>

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
Shimakaze

Typedefs

ShimakazeOptions
GiveReputationOptions
ResetUserReputationOptions
IncreaseUserReputationOptions
DecreaseUserReputationOptions
ReputationSettings

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

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)
Tama

Typedefs

TamaOptions
CreateOrUpdateOptions
listSubSettingsOptions
getSubSettingOptions
CreateOrUpdateSubSettingOptions

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

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.

Taihou

About

A promise-returning Node.js wrapper for weeb.sh

Resources

Readme

License

GPL-3.0 license
Activity
Custom properties

Stars

5 stars

Watchers

3 watching

Forks

1 fork
Report repository

Releases 7

Patch 2.0.7 but really it's 2.0.6 Latest
Sep 14, 2021
+ 6 releases

Packages

No packages published

Contributors 4

  •  
  •  
  •  
  •  

Languages