@cloudrac3r/in-your-element v1.0.0

In Your Element

A single file modern Matrix Application Service library written in JavaScript for Node.js, built on the h3 web server.

This is used in production by the Out Of Your Element Matrix-Discord bridge.

Example

Synapse needs an registration.yaml file to talk to your application service. You should create one according to the Synapse documentation and link it in to your Synapse configuration.

Then you can use In Your Element. Start with this example:

const {AppService} = require("@cloudrac3r/in-your-element")
const config = {
  url: "http://localhost:4873", // port for In Your Element to listen on; should be the same URL as in registration.yaml
  hs_token: "2a38549b2901ef759" // random string for authentication; should be the same hs_token as in registration.yaml
}
const as = new AppService(config).listen()

as.on("type:m.room.message", event => {
  // this function will be called every time a m.room.message event arrives
})

API Documentation

Config

• url: string
  • In Your Element will listen on this URL's port.
• listen: optional number/string
  • If provided, url is ignored. Custom port or UNIX socket to listen on.
• hs_token: string
  • The homeserver should use the same token for all requests. This verifies that incoming requests came from the homeserver.

Events

The AppService is an EventEmitter.

As per the above example, you can use .on(<name>, event => { ... to listen for incoming events.

• <name> is type:<event type> to listen for specific types of Matrix events and/or state events
  • for example, <name> is type:m.room.message to listen for room message events
  • for example, <name> is type:m.room.avatar to listen for the room's avatar changing
• <name> is ephemeral_type:<event type> for listen for specific ephemeral Matrix events
  • for example, <name> is ephemeral_type:m.typing to listen for typing start/stop events
• <name> is event to listen for ANY Matrix event and/or state event in the same listener function
• <name> is ephemeral to listen for ANY ephemeral event in the same listener function

Queries

as.roomQueryCallback = async alias => {
  // please read https://spec.matrix.org/v1.11/application-service-api/#querying
  // called when somebody looks up an unregistered room in the appservice's namespace
  // you must return true if you created the room for the alias during the function invocation
  // you must return false if you didn't
}

as.userQueryCallback = async mxid => {
  // please read https://spec.matrix.org/v1.11/application-service-api/#querying
  // called when somebody looks up an unregistered user in the appservice's namespace
  // you must return true if you created the user account for mxid during the function invocation
  // you must return false if you didn't
}

Client-Server API

In Your Element does not provide any helpers for the Matrix Client-Server API. In other words, if you want to make requests to the homeserver as your application service, you will have to add a library like matrix-js-sdk, or write the code yourself.