@laqus/notifications

This library is accessible as an NPM package and is recommended - as a must have - as the cornerstone for any NestJS-based project to ensure standardization. Its code is designed to be verbose, aiding in debugging and troubleshooting, while also being extensible, simplifying the addition of new features.

This package enables the sending of emails and notifications through the Laqus notifications service.

Requirements

Env vars

• LAQUS_NOTIFICATIONS_API_URL

LAQUS_APP_NAME
LOG_LEVEL [DEBUG|VERBOSE|LOG|INFO|WARNING|CRITICAL|ERROR|FATAL]
CLUSTERS (optional)

Installing

$ npm i @laqus/notifications

TO DOs

--

Sobre esta lib

Esta lib permite o envio de notificações e emails, bem como, consulta de notificações e subscrições. Ela provem essas funcionalidades abstraindo toda a API do serviço de Notifications da Laqus, provendo a correta tipagem dos dados e métodos.

Dependências

• @laqus/base
• @nestjs/common,
• @nestjs/config,
• @nestjs/core

Novos deploys/releases de melhorias e novas features

Deve-se apenas incrementar a versão da release no ./libs/notifications/package.json e fazer push na branch main e o processo de build e publicação no NPM será automatico.

Testes e debuggings

Este projeto é composto por uma api padrão REST com dependência na lib. O que torna o processo muito mais simples e rápido.

Estrutura do projeto

> .vscode   # Definições padrão do workspace
> libs      # Projeto da lib
> src       # Projeto host da lib, para testes, etc.

Estrutura da lib ( ./libs/notifications )

> src
    > application                   # implementação
        > emails
            > builders
            > models
        > notifications
            > builders
            > models
    > infrastructure                # implementação do client da API
        > laqus
            > notifications-api
                > models
                    > emails
                    > notifications
> LICENSE.md
> package.json
> README.md
> tsconfig.lib.json

Utilização

Tanto email e notifications são expostos através de uma interface própria. A instância destas interfaces devem ser criadas pelas respectivas factories.

Todos os métodos que podem lançar Errors estão anotados (@throws) com o tipo de Error que eles lançam, para um melhor e mais eficiente tratamento de erros nas app client. Ex:

export interface ILaqusNotificationsService {
	/**
	 * @throws ApiNotificationError
	 */
	ackNotification(notificationId: string, receiverId: string): Promise<boolean>;

	/**
	 * Envia uma notificação
	 * @param builder para criar, use a NotificationFactory
	 * @throws ApiNotificationError
	 * @throws InvalidSubscriptionError
	 * @throws ApiSubscriptionError*
	 */
	sendNotification(builder: AbstractNotificationBuilder): Promise<INotification | null>;
}

@Injectables

Os serviços injetáveis, tanto para Email quanto para Notifications são disponibilizados e que podem ser injetados como dependência são:

• LaqusNotificationsServiceBuilder
• LaqusEmailServiceBuilder

Ambos serviços são disponibilizados no escopo do lifecycle da aplicação, ou seja, singleton e, sendo assim, não podem requerer serviços que estão no escopo da requisição. Para isso, faz-se o uso de Service Providers, onde a própria classe que está tendo os serviços injetados na DI pode implementá-los.

Emails - (LaqusEmailServiceBuilder)

export class FooBar implements ILaqusLoggerServiceProvider, ICorrelationIdServiceProvider {
	public constructor(
        private readonly logger: SimpleConsoleLoggerService,
		private readonly correlationIdService: CorrelationIdService,
		private readonly laqusEmailServiceBuilder: LaqusEmailServiceBuilder		
	) {}

	public getCorrelationIdService(): CorrelationIdService {...}

	public getLoggerService(): ILaqusLogger {
		return this.logger;
	}

	public async example(): Promise<string> {
        //buscamos a instancia do service passando os providers requisitados (nesse caso, implementados em FooBar)
		const emailServiceInstance: IEmailService = 
            this.laqusEmailServiceBuilder.getEmailServiceInstance(this, this);
    }

A interface IEmailService fornece as seguintes funcionalidades:

export interface IEmailService {
    //Criar um template
	createTemplate(name: string, description: string, contents: string): Promise<ITemplate | null>;
	
    //Listagem dos templates
    getTemplates(): Promise<ITemplate[] | null>;

    //Busca do template pelo nome
	getTemplateByName(name: string): Promise<ITemplate | null>;

    //Busca do template pelo id
	getTemplateById(id: string): Promise<ITemplate | null>;
	
    //Envio do email
    sendEmail(builder: EmailBuilder): Promise<IEmail | null>;
}

Enviando um email

const content: string = '<h1>Olá!</h1>';

//Através da factory, escolhemos o tipo de email. Neste exemplo, email de conteúdo cru, de forma explícita e não por template
const rawContentEmailBuilder = EmailBuilderFactory.withContentRaw(content);

//definimos as informações
rawContentEmail
    .addAttachment("arquivo.pdf", buffer*) /*que saudade de C++, caras!*/
    .addAttachment("conciliacao.xsl", buffer*)
    .to('[e-mail]')
    .from('[e-mail]')
    .withSubject("Arquivos");

//por fim, a promessa do envio
await emailServiceInstance.sendEmail(rawContentEmail);

Notifications - (LaqusNotificationsServiceBuilder)

Para a obtenção da instância do service, procedemos da mesma forma que para o serviço de emails:

const service: ILaqusNotificationsService = this.notificationsService.getNotificationServiceInstance(this);

A interface ILaqusNotificationsService expõe as seguintes funcionalidades:

export interface ILaqusNotificationsService {
    //confirmação de recebimento da notificação
	ackNotification(notificationId: string, receiverId: string): Promise<boolean>;

    //Envio de notificação
	sendNotification(builder: AbstractNotificationBuilder): Promise<INotification | null>;

    //Listar notificações pendentes
	getNotAckedNotifications(args: IGetNotificationsArgs): Promise<INotification[]>;

    //Listar notificações
	getNotifications(args: IGetNotificationsArgs): Promise<INotification[]>;

    //Realizar a subscrição em um tópico
	subscribeToTopic(builder: SubscriptionsBuilder): Promise<ISubscription[]>;
    
    //Remover notificação
	removeNotification(notificationId: string, args?: IRemoveNotificationsArgs): Promise<boolean>;

    //Cancelar uma subscrição
	removeSubscription(args: IRemoveSubscriptionsArgs): Promise<boolean>;
}

Enviando uma notificação com audiência específica

No exemplo é mostrado um exemplo com vários atributos, o que tornará o código extenso. É importante notar que a maioria dos atributos são opcionais

const notification = await service.sendNotification(
    //através da factory, pedimos uma notificação com audiencia que queremos enviar de forma exclusiva, ignorando outros usuários subscritos
    NotificationFactory.buildNotificationWithSpecificAudience(
        //esse é o topico/evento/causa da notificação
        'ASSINATURA_CONCLUIDA',
        //titulo
        'O documento foi assinado',
        //Conteudo (pode ser qualquer coisa)
        'A minuta acabou de ser assinada por todos',
        //Id da correlação para rastrearmos qual operação originou esse evento
        this.correlationIdService.correlationId,
        //poderiamos informar o id da empresa (caso queiramos um dia, enviar pra todos da empresa X ou Y)
        null,
        //Esse é o id do usuário que causou esse evento
        'dc13fd39-4ef6-4f41-aaf0-b7a87beffbe0',
        //O nome do serviço que está disparando a notificação
        'DocSigner Api',
        //A prioridade de entrega
        NotificationPriority.LOW,
        //Como se espera que seja tratada no front, nesse caso, como um simples push de informativo
        NotificationType.INFORMATION
    )
    //adicionamos a audiencia especifica
    .addSpecificReceiverToTheAudience('leo')
    .addSpecificReceiverToTheAudience('grupo_operacoes')
    .addSpecificReceiverToTheAudience('dc13fd39-4ef6-4f41-aaf0-b7a87beffbe0')
    //podemos enviar informações adicionais, qualquer coisa que possa ser usada na leitura/ação/renderização da notificação
    .setMetadata({ ...})
    //podemos definir também o prazo de retenção da notificação
    .setRetentionWhenNotAck(10)
);

Enviando uma notificação para a audiência subscrita ao tópico

No exemplo é mostrado um exemplo que vai enviar a notificação para todos os usuários que estão subscritos para o topico 'INSTRUMENTO_EMITIDO' da empresa de id '00000000-1010-1111-0000-111111111111'.

Também podemos ver que esta notificação é uma solicitação de ação (ACTION_REQUEST), ou seja, baseado nisso, o frontend pode reagir de alguma maneira diferente, atualizando alguma coisa, perguntando confirmação do usuário, etc.

		const notification = await service.sendNotification(
			NotificationFactory.buildNotification(
				'INSTRUMENTO_EMITIDO',
				'A NC LNC20240078 foi emitida',
				'Clique <a href="#">aqui</a> para ver',
				this.correlationIdService.correlationId,
				'00000000-1010-1111-0000-111111111111',
				'dc13fd39-4ef6-4f41-aaf0-b7a87beffbe0',
				'Depositaria',
				NotificationPriority.LOW,
				NotificationType.ACTION_REQUEST
			)
		);

Realizando a subscrição de alguem a um tópico

No exemplo a seguir, estaremos subscrevendo o usuario "Wild Bill Wickup" para ser notificado sempre que houver uma EMISSAO_CANCELADA no seu escopo de empresa/cliente laqus

await service.subscribeToTopic(
    new SubscriptionsBuilder("EMISSAO_CANCELADA", "Id da empresa")
            .addSubscriber("01010101010", "Wild Bill Wickup")
)

Outros

Atualmente, a partir da versão 1.0.2-rc, alem de notificar através de push, podemos configurar que tais notificações também sejam entregues por email e/ou chat ou channel do Teams (Mas exige conf extra no Teams).

Build da lib para uso local

$ npm run build:lib