@whirlybird/interactions

Warning whirlybird is experimental software. Use at your own risk!

About

A simple low-level implementation for handling interactions via HTTP.

Ecosystem

Discover the rest of the whirlybird ecosystem!

Installing

Using Node.js

You will need Node.js v19.x.x or higher.

Install with the package manager of your choice:

$ npm i @whirlybird/interactions
$ pnpm i @whirlybird/interactions
$ yarn add @whirlybird/interactions

Enable ECMAScript modules (ESM) for your project:

{
  "type": "module"
}

Using Deno

You will need Deno v1.26.x or higher.

CLI Arguments: --allow-net --unstable

Import for GitHub:

export * from "https://github.com/apacheli/whirlybird/raw/dev/core/interactions/lib.js";

Getting Started

A simple export named startServer() is exposed if you just want to get a server running.

import { startServer } from "@whirlybird/interactions";

const handle = (interaction) => {
  if (interaction.data.name === "ping") {
    return {
      data: {
        content: "pong",
      },
      type: 4,
    };
  }
};

await startServer(
  1337,
  globalThis.Deno?.env.get("PUBLIC_KEY") ?? process.env["PUBLIC_KEY"],
  handle,
);

You can also use the low-level functions from whirlybird if you do not want to use startServer().

For Node.js, you can use the requestListener() export. It is designed to work with the native node:http module.

import { createKey, requestListener } from "@whirlybird/interactions";
import { createServer } from "node:http";

const cryptoKey = await createKey(process.env["PUBLIC_KEY"]);

const handle = async (interaction) => {
  // ...
};

const server = createServer(async (req, res) => {
  const response = await requestListener(req, cryptoKey, handle);
  res.writeHead(response.status, response.headers);
  res.end(response.body);
});

server.listen(1337);

requestListener() returns an object with the following properties (represented using a TypeScript interface):

export interface RequestListenerResponse {
  body: string;
  headers: Record<string, string>;
  status: number;
}

For Deno and Bun, a similarly low-level function named handleRequest() is exposed. It will return a Response.

import { createKey, handleRequest } from "@whirlybird/interactions";

const cryptoKey = await createkey(Deno.env.get("PUBLIC_KEY"));

const handle = async (interaction) => {
  // ...
};

await Deno.serve({ port: 1337 }, async (request) => {
  const response = await handleRequest(request, publicKey, handle);
  return response;
});

whirlybird also provides helper functions for building application commands and message components. They are completely optional to use if you want to use them.

Using application command helpers:

import { chatInputCommand, integer, string } from "@whirlybird/interactions";

const command = chatInputCommand("ping", "ping pong command", {
  options: [
    string("a", "look at me i am a string"),
    integer("b", "wow i am an integer", {
      max_value: 5,
      min_value: 1,
    }),
  ],
});

Using message component helpers:

import {
  actionRow,
  button,
  ButtonStyle,
  stringSelect,
} from "@whirlybird/interactions";

const data = {
  components: [
    actionRow([
      button("a", "Click Me!", ButtonStyle.Primary),
      button("b", "Click Me Too!", ButtonStyle.Secondary),
    ]),
    actionRow([
      selectMenu("c", [
        stringSelect("select me", "value"),
        stringSelect("all of the above", "Hello, World!"),
      ]),
    ]),
  ],
  content: "wow components are so cool",
};

return {
  data,
  type: 4,
};