Extensible multi-provider SMS sender with multi-strategy support.
Development status: need more feedback from real-world usage to reach v1. And upon API is stable more data stores, providers, and strategies will be added as needed. PR is always welcome.
Install
$ yarn add parrotlet # or npm install --save parrotlet
Usage
const db = redis // See example configuration at the Providers subsection below.const config = // ... // Provider configurations.const twilioProvider = configtwilioconst wavecellProvider = configwavecell // Sender configuration.const sender = providers: twilioProvider wavecellProvider strategies: db max: 4 // 4 messages per phone number within 1 hour. duration: 3600000 // Limit will be reset after 1 hour. timeBeforeReset: 50 * 1000 // After 50 seconds, it will reset to the first provider. // Send options.const sendOptions = to: '+66111222333' message: 'test message for multi-provider sms sender module (parrotlet)' // Sending messages.sender // Will be sent by Twilio // Will be sent by Wavecell // Will be sent by Twilio // Will not be sent but rejected with RateLimitExceededError
Tests
$ yarn test # or npm test, run unit test, does not require external setup. $ yarn test-integration # or npm run test-integration, run integration test, # requires external setup, see `test/integration/config.js.example`.
API
Sender(options)
options
dataStore
Type: DataStore
Required: false
Default: new DataStores.MemoryStore()
A DataStore
instance that will be used as context store for each strategy execution. Any DataStore
-compatible object can be used instead of the default in-memory store.
providers
Type: Array<Provider>
Required: true
An array of available Provider
(s). This provider list will go through each strategy execution and eventually be reduced to 1 provider on each Sender#send([sendOptions])
call.
strategy
Type: Strategy
(See Strategy
class description below)
Required: true
if strategies
is not provided
A strategy that will be executed when sending message to determine how to send.
strategies
Type: Array<Strategy>
Required: true
if strategy
is not provided
An array of Strategy
that will be executed, in order as provided, when sending message to determine how to send.
send(sendOptions)
Send an SMS message to the specified destination phone number. Return Promise
.
sendOptions
to
Type: String
Required: true
The destination phone number to send message to.
message
Type: String
Required: true
A Unicode-encoded message to send to destination phone number.
DataStore(options)
A key-value store. A DataStore
instance is just any object with #get()
and #set()
methods as specified below. Bundled DataStore
is MemoryStore
.
get(key)
Retrieve an associated value using key.
key
Type: String
Required: true
A key that will be used to retrieve an associated value.
set(key, value)
Retrieve an associated value using key.
key
Type: String
Required: true
A key that will be used to retrieve an associated value.
value
Type: Object
Required: true
Any value that can be serialized using JSON.stringify
. This value will be associated with the provided key and can be retrieved later by using that key.
Provider(options)
A Provider
instance is just any object with #send()
method as specified below. Bundled Provider
s are TwilioProvider
, WavecellProvider
and NullProvider
.
send(sendOptions)
Send an SMS message to the specified destination phone number. Return Promise
.
sendOptions
Type: Object
Required: true
See Sender#send()
.
Strategy(options)
A Strategy
instance is just any object with #execute()
method as specified below. Bundled Strategy
s are RateLimitStrategy
and RoundRobinStrategy
.
options
Vary for each type of strategy. See bundled Strategy
s below for example.
execute(sender, sendOptions, multi=false, reducedProviders = [])
sender
Type: Sender
Required: true
A Sender
instance. The list of available providers and the data store will be obtained from this instance.
sendOptions
Type: Object
Required: true
See Sender#send()
.
multi
Type: Object
Required: false
Default: false
Will be true when the strategy is executed as part of the multi-strategy execution.
reducedProviders
Type: Array
Required: false
Default: [ ]
An array of Provider
(s) that is reduced from previous strategy execution as part of the multi-strategy execution.
DataStores
Bundled data stores are MemoryStore
.
MemoryStore
In-memory data store. Simple and easiest way to use this module.
const memoryStore = memoryStorememoryStore
Providers
Bundled strategies are TwilioProvider
, WavecellProvider
, and NullProvider
.
TwilioProvider
Send SMS message via Twilio. Twilio credentials is required.
const twilioProvider = accountSid: 'account_sid_here' authToken: 'auth_token_here' from: 'from_phone_number_here' twilioProvider
WavecellProvider
Send SMS message via Wavecell. Wavecell credentials is required.
const wavecellProvider = accountId: 'account_id_here' subAccountId: 'sub_account_id_here' password: 'password_here' source: 'source_here' wavecellProvider
NullProvider
When calling #send()
will not actually send any message. Useful for development and testing.
const nullProvider = nullProvider // Not sending anything.
Strategies
Bundled strategies are RateLimitStrategy
and RoundRobinStrategy
.
RateLimitStrategy
Limit number of messages that can be sent to each destination phone number within the specified duration. Use ratelimiter
package internally. Redis instance is required.
const db = redis const rateLimitStrategy = db max: 4 // 4 messages per phone number within 1 hour. duration: 3600000 // Limit will be reset after 1 hour.
RoundRobinStrategy
All provided providers will be used as SMS message sender for each message sending attempt, in round-robin manner. Message sending attempt is identical if destination phone number and message body are the same.
const roundRobinStrategy = timeBeforeReset: 50 * 1000 // After 50 seconds, it will reset to the first provider.
License
Copyright 2017 Saran Siriphantnon <deoxen0n2@gmail.com> MIT License.