Elixcord plugins

FOR THE PERSON WRITING ONE

Write a
plugin.

One .js file, in CommonJS: it sets module.exports, which gives Elixcord its hooks, its chat commands and its settings, and may call elixcord's own API and nothing else. A call into it has 100 ms to answer; its JavaScript holds at most 32 MiB — a plugin that looped forever is stopped at its own error and switched off, so it can never hold the app still.

01

The shape of one

example.js — the first lines
02

The hooks

NameCalled withWhat it may answer
start() · stop() nothing The plugin switched on, and off. Set up and let go here.
transformOutgoing(msg) {room, content} {content} with what to send instead, or false to stop the message, or nothing to leave it. An edit goes through it too.
transformIncoming(msg) {room, id, author, content, own, bot, time} {content} to change what shows, or false to hide the message. Only the open room's timeline and its thread's come through.
onMessage(msg) the same as transformIncoming's Anything; nobody reads it.
run(args, ctx) — inside a commands entry args, the words after the name, and ctx = {room} {content}, which sends as a message, or {toast: {title, body}}, which tells of itself.

A hook that answers nothing leaves the message as it was. One that throws shows its error on the Plugins page and keeps running; one that doesn't answer in time is stopped, and its plugin with it.

03

The elixcord API

A plugin reads no file and opens no socket of its own: the calls below are everything it may do. Arguments and answers are plain values.

CallWhat it does
elixcord.notify(title, body) Tells of something, as a new message's notification does: the sound, the tray, and the system's notification — which opens nothing, as the plugin sent it.
elixcord.log(...) One line to Elixcord's own log, as [file.js] …; only the first line of each call is kept.
elixcord.storage.get(key)
elixcord.storage.set(key, value)
elixcord.storage.delete(key)
The plugin's own store, kept in the data folder's plugins-data.json, written whole. Each plugin's store is its own.
elixcord.settings.get(key) One of the plugin's settings, as the Plugins page set it; nothing for a key its schema doesn't declare.
elixcord.net.fetch(url, options) A fetch, as fetch's are: {method, headers, body}. It answers a promise with {status, body}, the body as text at most 10 MiB, or rejects with what went wrong. It goes nowhere unless the person turned Allow network access on for this plugin; off, the promise rejects at once.
04

Settings, as a schema

Whatever settings declares shows on the Plugins page, kept in the app's layout.json, and read back with elixcord.settings.get:

the settings schema
settings: {
  word:  { type: "text",   label: "Word to shout", default: "hey" },
  times: { type: "number", label: "How many",      default: 1 },
  on:    { type: "switch", label: "Be loud",       default: false },
}

A number's entry shows what was typed, and reads to the plugin as a number once it parses — a setting is never corrected under the person's keys.

05

What a plugin may not do

06

Publish it to the registry

  1. 1
    Make the file whole

    Give it name, description, version and author — the registry's pages read them — and try it in your own plugins folder first.

  2. 2
    Put it in the site's repo

    Drop the .js into plugins/files/ of the site's folder.

  3. 3
    Rebuild the registry

    Run node build.mjs: it reads each file's metadata, hashes the file, and rewrites plugins/index.json. A file that exports no name stops the build.

  4. 4
    Push

    Pages redeploys in under a minute, and every client's next check sees the newer version, downloads the file, checks its hash, and switches it on — by itself.

Whoever controls the registry decides what the clients run, so keep the repo and the deploy yours alone, and keep it on HTTPS. The hash is what makes a download worth writing: a file that doesn't answer for the hash the registry publishes is never installed.