MQ-SMS Integration

@nx/mq-sms is a multi-provider SMS management library. It wraps SMS provider APIs behind a unified interface with a client registry pattern. Currently supports VnPay as the sole SMS provider.

Quick Reference

Property	Value
Package	@nx/mq-sms
Location	third-parties/mq-sms/
Type	Library (consumed as a component by other services)
Consumed by	@nx/identity (OTP delivery)

Architecture

Providers

Provider	Code	Status
VnPay	MQSMSProviders.VNPAY = 'vnpay'	Active

VnPay Configuration

Field	Purpose
username / password	API authentication
partnerCode / secretKey	Partner identification
keyword	SMS keyword/brand name
brandName	Sender display name
encryptIv	IV for encrypted SMS mode (optional)
partnerPrivateKeyPath	RSA private key for security mode (optional)

VnPay endpoints used:

• /login — authentication (auto-managed by client)
• /send-sms — single SMS
• /v2/send-sms-security — encrypted single SMS
• /send-sms-list — batch SMS
• /v2/send-sms-list-security — encrypted batch SMS

SMSService

Core service methods:

Method	Purpose
sendSMS(request, clientName?)	Send single SMS via the default or named client
sendSMSSecurity(request, clientName?)	Send single encrypted SMS
sendSMSList(requests, clientName?)	Send batch SMS
sendSMSListSecurity(requests, clientName?)	Send batch encrypted SMS

Request format

interface TSendSmsRequest {
  messageId?: string;     // optional correlation ID
  destination: string;    // phone number
  content: string;        // message body
}

MQSMSClientRegistryService

Manages multiple provider client instances:

Method	Purpose
registerClient(name, client)	Register a provider client
unregisterClient(name)	Remove a client
getClient(name?)	Get client by name (or default)
getDefaultClient()	Get the current default client
setDefaultClient(name)	Switch the default client

Each registered client tracks: token, token expiry, last used timestamp.

REST Controller (Optional)

When enableControllers: true is set in MQSMSComponent options, an SMSController is registered:

Method	Path	Purpose
POST	/mq-sms/sms/send	Send single SMS
POST	/mq-sms/sms/send-security	Send encrypted SMS
POST	/mq-sms/sms/send-list	Send batch SMS
POST	/mq-sms/sms/send-list-security	Send batch encrypted SMS

All endpoints accept an optional clientName query parameter to select a specific provider client.

Integration with Identity

The identity service uses MQ-SMS for OTP (One-Time Password) delivery:

1. SMSComponent in identity registers MQSMSComponent at startup
2. Provider configs are loaded from the database (seeded by identity-0006-seed-sms-configurations)
3. SMSOTPSender injects SMSService and calls sendSMS() to deliver verification codes
4. SMS configs support multiple VnPay clients (different brand names/accounts)

Binding Keys

Key	Purpose
MQSMSBindingKeys.MQ_SMS_CLIENT_OPTIONS	Component configuration
MQSMSBindingKeys.MQ_SMS_CLIENT_PROVIDER	Client factory function
MQSMSBindingKeys.MQ_SMS_CLIENT_REGISTRY	Registry service instance

VnPay Response Codes

Code	Meaning
00	Success
02	Invalid length
04	Invalid authentication
05	Provider disconnected
06	IP not registered
21	Insufficient balance
85	Invalid sender
86	Invalid keyword
90	Duplicate message

Related Pages

Page	Description
Identity — Authentication	OTP delivery via MQ-SMS
MQ-Pay	Multi-provider payment (similar registry pattern)