Toju/docs-site/docs/plugin-development/api/events.md

sidebar_position

sidebar_position
7

Events API

Plugin events allow plugins to publish and subscribe to declared server or P2P events.

Required Capabilities

Method	Capability
events.publishServer(eventName, payload)	events.server.publish
events.subscribeServer(subscription)	events.server.subscribe
events.publishP2p(eventName, payload)	events.p2p.publish
events.subscribeP2p(subscription)	events.p2p.subscribe

Declare Events in the Manifest

{
  "events": [
    {
      "eventName": "poll:vote",
      "direction": "p2pHint",
      "scope": "channel",
      "maxPayloadBytes": 2048
    },
    {
      "eventName": "moderation:flag",
      "direction": "serverRelay",
      "scope": "server",
      "maxPayloadBytes": 4096
    }
  ]
}

Publish and Subscribe to P2P Events

export function activate(context) {
  context.subscriptions.push(context.api.events.subscribeP2p({
    eventName: 'poll:vote',
    handler: (event) => {
      context.api.logger.info('Vote received', {
        optionId: event.payload?.optionId,
        voterName: event.payload?.voterName,
        eventId: event.eventId
      });
    }
  }));

  context.api.events.publishP2p('poll:vote', {
    pollId: 'raid-night-2026-04-29',
    optionId: 'dungeon',
    voterName: 'Alice'
  });
}

Publish and Subscribe to Server Events

export function activate(context) {
  context.subscriptions.push(context.api.events.subscribeServer({
    eventName: 'moderation:flag',
    handler: (event) => {
      context.api.logger.warn('Moderation flag received', {
        messageId: event.payload?.messageId,
        reason: event.payload?.reason
      });
    }
  }));

  context.api.events.publishServer('moderation:flag', {
    messageId: 'msg-20260429-flagged',
    reason: 'Possible spam link',
    reportedBy: 'user-alice-01'
  });
}

Example event envelope:

{
  "type": "plugin_event",
  "eventName": "poll:vote",
  "pluginId": "example.polls",
  "serverId": "room-7ebdde75",
  "eventId": "event-1777473600000-1",
  "emittedAt": 1777473600000,
  "payload": {
    "pollId": "raid-night-2026-04-29",
    "optionId": "dungeon",
    "voterName": "Alice"
  }
}