@planorjs/core

    1.1.2 • Public • Published

    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 🐬

    ko-fi

    Install

    npm i @planorjs/core

    DownloadsWeekly Downloads

    1

    Version

    1.1.2

    License

    MIT

    Unpacked Size

    129 kB

    Total Files

    24

    Last publish

    Collaborators

    • muratgozel