π§©Extensions
Learn how to write your own extensions.
Writing extensions for WrangleBot is very simple and only requires a text editor to get started.
We recommend using an IDE such as Visual Studio Code, WebStorm or at the very least a text editor with syntax highlighting such as Sublime.
Choosing your Extension
WrangleBot supports two extension types: hooks and endpoints
Hook
Whenever WrangleBot does something, it fires events, these events contain data, that you can act on.
Endpoint
An endpoint acts as any other endpoint on the API, you can call it via /api/v1/your-endpoint/ using any curl or http request.
Adding your Extension
Start by creating a folder called custom
in your wranglebot
folder in your user home folder, i.e. /Users/axelrothe/wranglebot/
Within this folder, create another folder and give it a unique name. This will be your extension root folder.

Create one or both folders, for hooks
and endpoints
and create a .js file, the name should reflect the script functionality, i.e. create-new-project.js

Hook
module.exports = {
name: "example-external-hook",
description: "An example hook that is external to the bot",
version: "0.0.1",
events: ["notification"],
handler: async (event, data, wranglebot) => {
const libs = await wranglebot.query.library.many().fetch();
console.log(`There are currently ${libs.length} libraries loaded.`);
},
};
name : string
give your extension a name that you can use reference console logs in log.txt
description : string
describe your extension and what it is for. This will be used to display the current running extensions.
version : string
the version number. must adhere to semantic versioning
events : string[]
the id's of the events to listen to. It's possible to listen to multiple events per Hook, though it might be easier to write a hook per event.
handler : Function
The handler expects a Promise
to be returned.
To do this you can either use the async
or Promise
syntax.
event : string // the event id
data : any // see event return value
wranglebot : WrangleBot // current instance
Endpoints
module.exports = {
method: "get",
requiredRole: ["admin", "maintainer", "contributor"],
url: "/example/01",
handler: async (request, result, wranglebot, server) => {
const libs = await wranglebot.query.library.many().fetch();
return {
status: 200,
result: `There are currently ${libs.length} libraries loaded.`
}
},
};
method : string
Must be either get
, put
, post
, notify
, patch
or delete.
This defines the REST endpoints method.
requiredRole : string[]
An array of all roles that can have access to this endpoint. If you leave this property blank it will default to any registered user.
Possible Roles are: admin
, maintainer
, contributor
, curator
url : string
The URI to the endpoint. You can define parameters by using the :
operator, e.g.
/custom-endpoint/:paramA/:paramB
You can then query those parameters with request.params
.
const { paramA, paramB } = request.params;
To get the body of a POST
or PUT
request, you use request.body
handler : async Function
The handler expects a Promise
to be returned.
To do this you can either use the async
or Promise
syntax.
The handler will catch your Errors and return a generic Error to the user. The log will offer better insight into what went wrong.
request : Request //use to get params, body and auth
result : Result, //the result object, best left alone
wranglebot : WrangleBot, //current instance
server : RESTServer //Http Server
You must return a valid RouteResult, as defined below. You can use any valid 3-digit HTTP Error Code.
// @define RouteResult
{
status: number, // e.g. 200 OK, 404 NOT FOUND, 400 BAD REQUEST
result: any // your result
}
Importing Third Party Libraries
WrangleBot extensions currently do not support automatic importing of libraries via the node_module
folder. You will need to directly require the script.
//instead of
const thirdparty = require('mythirdpartylib');
// do
const thirdparty = require('./node_modules/mythirdpartylib/dist/index.js')
Sharing your Creations
We'd love to hear about your extensions and how you implemented them. You can share them with an active community over at our Discord Server and get feedback and recognition π
Last updated
Was this helpful?