@planorjs/core

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: '[e-mail]'}, {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: '[e-mail]',
  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: '[e-mail]',
  password: '----'
}

const service = new PlanorServiceSmtp(credentials)

await planor.addService(service)

Send An Email

const result = await planor.sendEmail('VERIFY_SIGNIN', {to: '[e-mail]'}, {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: ['[phone]']}, {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 🐬