@spraxium/signal

@spraxium/signal implements an async, unidirectional event system for Spraxium bots using Discord webhooks as the transport layer. A signal is a typed envelope containing an event name, an optional guild ID, a timestamp, and a Zod-validated payload. External services dispatch signals by posting to a Discord webhook that delivers the message to a private channel monitored by the bot. The bot reads each message, verifies the HMAC-SHA256 signature, deduplicates by nonce, and routes the payload to the correct handler.

Handlers are defined with the @SignalListener class decorator and the @OnSignal method decorator. Each @OnSignal registration can optionally declare a Zod schema, and the framework validates the incoming payload against it before calling the handler. Because handlers are resolved through the Spraxium DI container, they can inject any registered service and behave identically to other components in the application.

Installation

npm install @spraxium/signal

Usage

// Listener class: handles incoming signals
import { Injectable } from '@spraxium/common';
import { OnSignal, SignalListener } from '@spraxium/signal';
import type { SignalEnvelope } from '@spraxium/signal';
import { z } from 'zod';

const configUpdateSchema = z.object({ prefix: z.string().min(1).max(5) });

@SignalListener()
export class ConfigUpdateListener {
  @OnSignal('config.update', {
    schema: configUpdateSchema,
  })
  async onConfigUpdate(
    payload: { prefix: string },
    envelope: SignalEnvelope,
  ): Promise<void> {
    console.log(`Guild ${envelope.guildId} updated prefix to ${payload.prefix}`);
  }
}

// app.module.ts
import { Module } from '@spraxium/common';
import { SignalModule } from '@spraxium/signal';
import { ConfigUpdateListener } from './config-update.listener';

@Module({
  imports: [SignalModule],
  providers: [ConfigUpdateListener],
})
export class AppModule {}

// spraxium.config.ts: signal config lives here
import { defineConfig } from '@spraxium/core';
import { defineSignal } from '@spraxium/signal';

export default defineConfig({
  plugins: [
    defineSignal({
      channelId: process.env.SIGNAL_CHANNEL_ID ?? '',
      allowedWebhookIds: [process.env.SIGNAL_WEBHOOK_ID ?? ''],
      hmacSecret: process.env.SIGNAL_HMAC_SECRET ?? '',
      deleteAfterProcessing: true,
    }),
  ],
});

Links

npm · GitHub · Zod · Documentation

License

Apache 2.0