Make your bookmarks YMAL available in Slack

This module will add a POST request to your Express or Fastify webserver that Slack can use as a webhook. It is a wrapper around Bookworms so it is recommended you understand how that works first.

This module is currently a prototype but is fully usable.

How does it work?

• When a Slack slash command is called Slack sends a POST request a webhook URL
• Your webserver will get the generate a response based on the POST body and respond with a flavor of markdown designed for Slack
• Your Slack bot will respond privately to the user with their requested bookmarks

The following examples are based on an active Slack bot using Bookworms, how to do this and set up the command words are documented at the bottom.

All commands

If the user didn't select a top level Bookworms folder or passed all the response will be a list of available commands.

/bookmarks all

Specific bookmarks command

The commands from the all command is generated by the top level folders. You use the name of the top level folder and pass it to your slash command.

/bookmarks help

Getting started

$ npm i bookworms-slack-webhook

Once its added to your project you can import it into your webserver.

Express

import express from "express";
import { expressWorms } from "bookworms-slack-webhook";
const app = express();
const port = 3000;

await expressWorms(app, {
  path: "https://raw.githubusercontent.com/thearegee/bookworms/main/demo/config/bookmarks.yaml",
});

app.get("/", (req, res) => {
  res.send("Hello World!");
});

app.listen(port, () => {
  console.log(`Example Express app listening on port ${port}`);
});

• app - Required the instance of your express server
• options - object of options for setting up Bookworms
  • path - Required where the Bookworms bookmarks are coming from, this could be a local or remote YAML file. For more information see Bookworms
  • route - the path on your webservers hostname Slack will use as a webhook. This parameter is optional with a default value of: /webhooks/slack/bookworms

Fastify

import Fastify from "fastify";
import { fastWorms } from "bookworms-slack-webhook";
const app = Fastify();
const port = 3000;

app.register(fastWorms, {
  path: "https://raw.githubusercontent.com/thearegee/bookworms/main/demo/config/bookmarks.yaml",
});

app.get("/", (request, reply) => {
  reply.send("Hello World!");
});

app.listen(port, () => {
  console.log(`Example Fastify app listening on port ${port}`);
});

• options - object of options for setting up Bookworms
  • path - Required where the Bookworms bookmarks are coming from, this could be a local or remote YAML file. For more information see Bookworms
  • route - the path on your webservers hostname Slack will use as a webhook. This parameter is optional with a default value of: /webhooks/slack/bookworms

Integrated with Slack

You can add Bookworms to your already existing bot or read about how to create a Slack bot.

This webhook works on using Slash commands.

• Command - The slpash command you want to use to trigger the webhook
• Request URL - The full URL for your service and your route path, this needs to be internet facing for Slack to call it
• Short Description - Help your users know what your the command does
• Usage Hint - A sample command for your users to know how to get started all will return all the top level folders

Todo

• Bookworms was not designed to be included as part of a webserver so it uses console log and also exits process on an error. These are not ideal for web service so need to be fixed
• Test automation
• Would be nice to drill into deep folders

Credits

The Bookworms logo was created by gullwing.io.