Signal on the Bot Side

Bot-side responsibilities

On the receiver side, Signal is responsible for protecting your bot runtime before any domain mutation happens. The SignalRegistry discovers listener classes during boot, the SignalValidator enforces ten transport rules, the NonceCache prevents replay attacks, and the SignalProcessor orchestrates the entire pipeline. Your handlers only execute after all these layers have approved the incoming envelope.

This separation is the key architectural benefit. Your domain handlers stay focused on business intent, applying role changes, updating configurations, posting announcements, while the protocol layer owns trust, format, and routing concerns. No handler needs to check whether the webhook is authorized or whether the signature is valid because those checks already happened upstream.

Plugin configuration

The bot-side Signal module reads its configuration from a plugin entry produced by the defineSignal factory. This factory is exported from @spraxium/signal and produces a typed SpraxiumPlugin entry that must be added to the plugins array in spraxium.config.ts. The configuration defines the trust boundaries and operational controls for the receiver pipeline.

Split config pattern

The recommended approach is to extract the Signal config into a dedicated file inside config/ and import the constant in spraxium.config.ts. This keeps operational policy explicit and allows security teams to audit Signal boundaries without parsing unrelated application setup.

import { defineSignal } from '@spraxium/signal';

export const signalPlugin = defineSignal({
  channelId:             process.env.SIGNAL_CHANNEL_ID!,
  allowedWebhookIds:     [process.env.SIGNAL_WEBHOOK_ID!],
  hmacSecret:            process.env.SIGNAL_HMAC_SECRET!,
  deleteAfterProcessing: true,
  debug:                 false,
});

The @SignalListener decorator

The @SignalListener() decorator marks a class as a container for Signal event handlers. It serves the same role that @Listener() serves for Discord events and @PrefixCommand() serves for prefix commands. During boot, the SignalRegistry scans provider instances and identifies classes decorated with @SignalListener(), then inspects each method for @OnSignal() metadata.

Internally, @SignalListener() applies @Injectable() automatically, so the class participates in dependency injection without needing a separate decorator. The class must be listed in the providers array of a module that imports SignalModule.

import { SignalListener, OnSignal } from '@spraxium/signal';
import type { SignalEnvelope } from '@spraxium/signal';

@SignalListener()
export class GuildConfigSignal {
  @OnSignal('config.update')
  async onConfigUpdate(
    payload: unknown,
    envelope: SignalEnvelope,
  ): Promise<void> {
    // Domain logic anchored to envelope.guildId
  }
}

The @OnSignal decorator

The @OnSignal() decorator registers a method as a handler for a specific Signal event. The first argument is the event name, which must match exactly the event name used by the emitter. The optional second argument is an options object that can include a Zod schema for payload validation.

When the Signal pipeline receives an envelope with a matching event name, the decorated method is invoked with two arguments: the payload (optionally validated by Zod) and the full SignalEnvelope. The envelope gives you access to guildId, nonce, sentAt, and other metadata for scoping and auditing.

import { SignalListener, OnSignal } from '@spraxium/signal';
import type { SignalEnvelope } from '@spraxium/signal';
import { z } from 'zod';

const ConfigUpdateSchema = z.object({
  prefix: z.string().min(1).max(5),
  language: z.enum(['en', 'pt', 'es']).optional(),
});

@SignalListener()
export class GuildConfigSignal {
  @OnSignal('config.update', { schema: ConfigUpdateSchema })
  async onConfigUpdate(
    payload: z.infer<typeof ConfigUpdateSchema>,
    envelope: SignalEnvelope,
  ): Promise<void> {
    // payload is validated and typed, envelope provides guild context
  }
}

Event name as a stable contract

The first argument in @OnSignal('config.update') is the event identity used by Signal routing. It is the key that maps incoming envelopes to the correct listener, it is a producer-consumer contract between emitter code and bot listeners, and it is an operational reference for logs, dashboards, and incident analysis.

Treat event names as stable domain APIs. If payload semantics must change in a non-backward-compatible way, prefer introducing a new event name such as config.update.v2 instead of silently reusing the same one. Renaming an event without coordinating producers and listeners causes messages to be silently ignored or dispatched to the wrong handler.

Module and listener wiring

The module structure for Signal follows the standard Spraxium pattern. Create a feature module that imports SignalModule and registers your listener classes in the providers array. The SignalModule is a global module that provides the core services (SignalValidator, SignalRouter, SignalProcessor, SignalRegistry, NonceCache), so you only need to import it once in any module that contains listeners.

import { Module } from '@spraxium/common';
import { SignalModule } from '@spraxium/signal';
import { GuildConfigSignal } from './listeners/guild-config.signal';
import { BillingSignal } from './listeners/billing.signal';

@Module({
  imports: [SignalModule],
  providers: [GuildConfigSignal, BillingSignal],
})
export class AppSignalModule {}

Bot-side lifecycle flow

Dependency injection in listeners

Because @SignalListener() applies @Injectable() automatically, your listener classes participate in the standard dependency injection system. You can inject services, repositories, and other providers through constructor parameters, just like any other injectable class in Spraxium.

import { SignalListener, OnSignal } from '@spraxium/signal';
import type { SignalEnvelope } from '@spraxium/signal';
import { GuildSettingsService } from '../../services/guild-settings.service';

@SignalListener()
export class GuildConfigSignal {
  constructor(private readonly guildSettings: GuildSettingsService) {}

  @OnSignal('config.update')
  async onConfigUpdate(
    payload: { prefix: string },
    envelope: SignalEnvelope,
  ): Promise<void> {
    await this.guildSettings.updatePrefix(envelope.guildId, payload.prefix);
  }
}

Debug diagnostics

When debug is set to true in the Signal config, the framework emits detailed diagnostic messages for every step of the validation and processing pipeline. Each message includes a [SignalValidator] or [SignalProcessor] prefix and reports the exact rule that passed or failed, the nonce status, the handler resolution result, and the Zod validation outcome.

This diagnostic output is invaluable during initial integration and incident investigation. However, it should be disabled in steady-state production because it significantly increases log volume on channels with frequent Signal traffic. A practical pattern is to enable debug only in neutral/staging environments or temporarily during incident analysis.