Channel preferences

Users want control: email me invoices, but not in Slack. The preferences package adds an opt-out layer — a channel is allowed unless a user has explicitly muted it — and wires it straight into delivery, so a muted channel is skipped automatically. No shouldSend boilerplate on every notification.

Register the module

import { PreferencesModule } from '@dudousxd/nestjs-notifications-preferences';

@Module({
  imports: [
    PreferencesModule.forRoot(), // in-memory store
    // PreferencesModule.forRoot({ store: PrismaPrefStore }), // your own store
  ],
})
export class AppModule {}

PreferencesModule.forRoot() defaults to an in-memory store; pass a store class implementing PreferenceStore to persist preferences in your database. It registers globally by default.

Mute and unmute

Inject NotificationPreferences and toggle channels for a user:

import { Injectable } from '@nestjs/common';
import { NotificationPreferences } from '@dudousxd/nestjs-notifications-preferences';

@Injectable()
export class PreferencesService {
  constructor(private readonly prefs: NotificationPreferences) {}

  async muteEmail(user: User) {
    await this.prefs.mute(user, 'mail');
  }

  async unmuteEmail(user: User) {
    await this.prefs.unmute(user, 'mail');
  }

  async emailMuted(user: User) {
    return this.prefs.isMuted(user, 'mail'); // boolean
  }
}

The target is any notifiable (its reference is derived via the core notifiableRef — so it needs a @NotifiableId()/toNotifiableRef()), or a plain { type, id } reference.

Muted channels are auto-skipped

You don't check preferences when sending — the gate does it for you. A send to a user who muted mail simply skips that channel; the result records it as skipped, and the channel never runs:

await this.prefs.mute(user, 'mail');

const [result] = await notifications.send(user, new InvoicePaid(invoice));
result.results;
// [
//   { channel: 'mail', status: 'skipped' },
//   { channel: 'database', status: 'sent' },
// ]

This is the same skipped status produced by a notification's own shouldSend — the preference gate just applies it app-wide from stored user choices.

Per-tenant preferences

In a multi-tenant app a user's choices differ per workspace. Scope preferences with forTenant(id) — a mute is then keyed by user and tenant:

await this.prefs.forTenant('acme').mute(user, 'mail');   // muted only in Acme
await this.prefs.forTenant('globex').isMuted(user, 'mail'); // false — different workspace

The gate is tenant-aware to match: a send scoped to acme honours the acme-scoped mutes, while a send to another tenant (or an unscoped one) is unaffected.

Bring your own store

The default InMemoryPreferenceStore is fine for tests and single-process apps. For production, implement PreferenceStore against your database and pass it to forRoot({ store }):

import type { PreferenceKey, PreferenceScope, PreferenceStore } from '@dudousxd/nestjs-notifications-preferences';

@Injectable()
export class PrismaPrefStore implements PreferenceStore {
  isMuted(key: PreferenceKey): Promise<boolean> { /* … */ }
  mute(key: PreferenceKey): Promise<void> { /* … */ }
  unmute(key: PreferenceKey): Promise<void> { /* … */ }
  mutedChannels(scope: PreferenceScope): Promise<string[]> { /* … */ }
}

Each PreferenceKey carries the optional tenant, the notifiable's type/id, and the channel — everything you need to store and query a row.

Beyond opt-out: the preference center

Muting is a single on/off per channel. Real apps need a matrix: a user wants billing emails but not billing push, product updates only weekly, and security alerts they can't turn off at all. That's the preference center — a grid of categories × channels, plus a per-category digest frequency.

A notification declares its category; everything else falls out of the user's matrix.

@Notification()
export class InvoicePaid {
  readonly category = 'billing'; // ← the row in the matrix

  via() {
    return [Mail, Database];
  }
  // ...
}

Register the center with your category definitions instead of forRoot:

import { PreferencesModule } from '@dudousxd/nestjs-notifications-preferences';

PreferencesModule.forCenter({
  categories: [
    { key: 'billing', label: 'Billing', allowDigest: true },
    { key: 'product', label: 'Product updates', allowDigest: true, defaultChannels: ['mail'] },
    { key: 'security', label: 'Security alerts', mandatory: true }, // can't be turned off
  ],
});

forCenter binds a category-aware gate to the same NOTIFICATION_PREFERENCE_GATE token, so the ChannelRunner enforces the matrix automatically:

• a disabled (category × channel) toggle → that channel is skipped;
• a category set to daily/weekly digest → instant delivery is suppressed (a scheduled digest job, which you own, would batch and send those later);
• a mandatory category (e.g. security) is always delivered, ignoring the matrix.

A UI in one controller

createPreferenceCenterController exposes the matrix as REST, ready for a settings screen:

import { createPreferenceCenterController } from '@dudousxd/nestjs-notifications-preferences';

const PreferenceCenterController = createPreferenceCenterController({
  resolveRef: (req) => ({ type: 'User', id: req.user.id }),
});

Every route except GET /preferences/categories is scoped to the notifiable resolveRef returns. Decide who reaches the controller with decorators (or by mounting it in your own module) — see Authorization of the mounted routes:

createPreferenceCenterController({
  resolveRef: (req) => ({ type: 'User', id: req.user.id }),
  decorators: [UseGuards(AuthenticationGuard), Can(PreferencesPolicy, 'manage')],
});

If an app imports both forRoot() and forCenter(), the preference center's gate decides every delivery, whichever module is imported first. The opt-out mutes set through NotificationPreferences are then not consulted by the gate, so store the user's choices in the center's matrix.