Back to Integrations
Enterprise Backend

Herald + NestJS

Integrate Herald as a proper NestJS module with dependency injection, global configuration, and feature modules. The HeraldModule provides a HeraldService that can be injected into any controller or service — following NestJS best practices for scalable backend architecture.

Ready to ship?

Start sending zero-PII notifications in minutes.

REGISTER YOUR WALLET
ZK-SECURE SOLANA NATIVE

Package: @herald-protocol/sdk

Install: npm install @herald-protocol/sdk @nestjs/common

View full example on GitHub →

Herald Module

Global module providing Herald client and service via DI.

Source →
NestJS / Herald Module
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
import { Global, Module } from '@nestjs/common';
import { Herald } from '@herald-protocol/sdk';
import { HeraldService } from './herald.service';


@Global()
@Module({
  providers: [
    {
      provide: 'HERALD_API_KEY',
      useValue: process.env.HERALD_API_KEY!,
    },
    {
      provide: Herald,
      useFactory: (apiKey: string) => new Herald({ apiKey }),
      inject: ['HERALD_API_KEY'],
    },
    HeraldService,
  ],
  exports: [Herald, HeraldService],
})
export class HeraldModule {}

Herald Service

Injectable service wrapping all Herald SDK methods.

Source →
NestJS / Herald Service
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
import { Injectable } from '@nestjs/common';
import { Herald } from '@herald-protocol/sdk';


export interface NotifyOptions {
  wallet: string;
  subject: string;
  body: string;
  category?: 'defi' | 'governance' | 'system' | 'marketing';
  receipt?: boolean;
  idempotencyKey?: string;
}


@Injectable()
export class HeraldService {
  constructor(private readonly herald: Herald) {}


  async send(options: NotifyOptions) {
    return this.herald.notify(options);
  }


  async sendBulk(options: { wallets: string[]; subject: string; body: string; category?: string }) {
    return this.herald.notifyBulk(options);
  }


  async getStatus(notificationId: string) {
    return this.herald.getStatus(notificationId);
  }


  async getUsage() {
    return this.herald.getUsage();
  }


  async isRegistered(wallet: string) {
    return this.herald.isRegistered(wallet);
  }
}

Liquidation Controller

Feature controller injecting HeraldService for defi alerts.

Source →
NestJS / Liquidation Controller
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
import { Controller, Post, Body } from '@nestjs/common';
import { HeraldService } from '../herald.service';


@Controller('liquidation')
export class LiquidationController {
  constructor(private readonly herald: HeraldService) {}


  @Post()
  async send(@Body() body: {
    wallet: string;
    positionId: string;
    healthFactor: number;
    debtAmount: number;
    asset: string;
  }) {
    const idempotencyKey = `liquidation_${body.positionId}_${Math.floor(Date.now() / 30000)}`;


    return this.herald.send({
      wallet: body.wallet,
      subject: `⚠️ Liquidation Warning — Health factor: ${body.healthFactor}`,
      body: [
        `Position #${body.positionId} is approaching liquidation.`,
        `Health factor: ${body.healthFactor}`,
        `Debt: ${body.debtAmount} ${body.asset}`,
        `Add collateral or repay immediately.`,
      ].join('\n'),
      category: 'defi',
      receipt: true,
      idempotencyKey,
    });
  }
}

App Module

Import HeraldModule and register feature controllers.

Source →
NestJS / App Module
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
import { Module } from '@nestjs/common';
import { HeraldModule } from './herald.module';
import { LiquidationController } from './liquidation/liquidation.controller';
import { GovernanceController } from './governance/governance.controller';
import { YieldController } from './yield/yield.controller';
import { WebhookController } from './webhooks/webhook.controller';


@Module({
  imports: [HeraldModule],
  controllers: [
    LiquidationController,
    GovernanceController,
    YieldController,
    WebhookController,
  ],
})
export class AppModule {}

Common Patterns

Global HeraldModule with factory provider
Inject HeraldService into feature controllers
Liquidation, Governance, Yield modules
Webhook controller with signature verification

Start building with Herald

Clone the examples repo, copy the code that fits your stack, and deploy.

VIEW ON GITHUBREAD DOCS