README
planor
Email and sms sending library with parsable templates and plugins. ✈️
Planor is based on MIMEText. It has a simple template engine and a wrapper class PlanorService
to send emails and sms. Once you setup its very easy to use.
await planor.sendEmail('VERIFY_SIGNIN', {to: 'test@test.com'}, {code: '918273'})
// check your email for verification code!
Install
npm i @planorjs/core
Install Plugins
Choose the services you would like to use to send email and/or sms and install its plugin:
npm i @planorjs/plugin-gmail
npm i @planorjs/plugin-smtp
npm i @planorjs/plugin-postmark
Usage
Importing
import {Planor, PlanorService, PlanorTemplate} from 'planor'
or
const {Planor, PlanorService, PlanorTemplate} = require('planor')
This library is compatible with all node/lts versions. If your node version is < 14 then:
import {Planor, PlanorService, PlanorTemplate} from 'planor/node/lts'
Initiate Planor
const planor = new Planor()
Initiate Templates
Create a new PlanorTemplate
instance with channel
, id
, locale
and template
in order.
const emailTemplate = new PlanorTemplate('email', 'VERIFY_SIGNIN', 'en_US', [
'Your {{project}} Verification Code', // email subject
'You have requested to signin to {{project}} and your verification code is "{{code}}"' // email content
])
planor.addTemplate(emailTemplate)
Channel is one of email and sms. Id is the name you chose to remember when sending emails. locale is currently experimental state but you still need to specify it.
Template is an array of subject and content. The example above creates a plaintext template. To create an html template:
const emailTemplate = new PlanorTemplate('email', 'VERIFY_SIGNIN', 'en_US', [
'Your {{project}} Verification Code', // email subject
{type: 'text/html', template: 'You have requested to signin to {{project}} and your verification code is "{{code}}"'} // email content
])
planor.addTemplate(emailTemplate)
Just wrapped it in an object with a type property. It also supports parsing mjml templates:
const emailTemplate = new PlanorTemplate('email', 'VERIFY_SIGNIN', 'en_US', [
'Your {{project}} Verification Code', // email subject
{type: 'text/mjml', template: '<mjml>You have requested to signin to {{project}} and your verification code is "{{code}}"</mjml>'} // email content
])
planor.addTemplate(emailTemplate)
Configure Template Literals
PlanorTemplate supports template literal parsing but template literals kept inside Planor not PlanorTemplate.
planor.updateTemplateLiterals({project: 'SomeApp'})
Add Email Service
By default, there is no email service provider. You need to add one. Gmail service for example:
import PlanorServiceGmail from '@planorjs/plugin-gmail'
const credentials = {
sender: 'test@test.com',
gcloudProject: 'project-name',
googleApplicationCredentials: '/path/to/googleCloudServiceAccount.json'
}
await planor.addService(new PlanorServiceGmail(credentials))
Or SMTP server:
import PlanorServiceSmtp from '@planorjs/plugin-smtp'
const credentials = {
host: 'mail.test.net',
port: '465',
username: 'test@test.com',
password: '----'
}
const service = new PlanorServiceSmtp(credentials)
await planor.addService(service)
Send An Email
const result = await planor.sendEmail('VERIFY_SIGNIN', {to: 'some@email.tld'}, {code: '918273'})
The first argument is the id
of the template. The second argument is options for MIMEText and may contain service specific options. The third argument is one-time template literals.
As a result, you will get an object that contains a result.id
.
You can add as many services as you like. Planor will try to send until it sends successfully.
You can collect errors with planor.getErrors()
. sendEmail
won't throw you anything.
Add SMS Service
Messagebird, currently the only plugin available for sms:
import PlanorServiceMessagebird from '@planorjs/plugin-messagebird'
const credentials = {
origin: '...',
accessKey: '...'
}
const service = new PlanorServiceMessagebird(credentials)
Send An SMS
const result = await planor.sendSms('VERIFY_SIGNIN', {recipients: ['+1234567890']}, {code: '918273'})
Creating Plugins
A template for the plugin:
class PlanorServiceTest extends PlanorService {
constructor() {
super('nameOfTheService', 'email')
this.credentialKeys = ['from', 'token']
}
// create client
async getClient() {
const creds = super.getCredentials()
process.env.TEST_API_KEY = creds.apiKey
this.client = 'Test Client'
}
// actually send the message
async send(mimemsg, mimeopts) {
return {
apiKey: process.env.TEST_API_KEY,
secret: super.getCredentials().secret
}
}
}
The mimemsg here is an instance of MIMEText
Version management of this repository done by releaser 🚀
Thanks for watching 🐬