@onderwijsin/keystone_utils v0.1.2

Keystone Utils

A library of utility functions for keystone js 6 applications. Utilities that are included:

• Mailer
• SlateBlockCounter
• SlateHelpers

Mailer

You can use the Mailer class to create a new mailer object. With this object, you can send all sorts of email through the Mailgun API. It contains a general, but dynamic template that is compiled to HTML (with EJS, yes that EJS) based on the variables you provide.

You can either send a 'clean' email where you have control over every variable, or you can send an email by template. You can also set the theme and sender info of the email by providing the proper app name. Currently the following themes and templates are supported:

Themes: 'onderwijsloket' | 'traineesinonderwijs' | 'voorbereiden' | 'hulpvoordeklas'
Template: 'confirm_account' | 'welcome_user' | 'reset_password' | 'magic_auth'

How to use

import { Mailer } from '@onderwijsin/keystone_utils'

const mailer = new Mailer({
    config: {
        MAILGUN_API_KEY: '<private_mailgun_api_key>',
        MAILGUN_HOST: 'https://api.eu.mailgun.net'
    }
})

// Send a clean email
mailer.send({
    config: {
        theme: 'traineesinonderwijs',
    },
    head: {
        to: 'remihuigen@gmail.com',
        from: {
            name: 'Trainees in onderwijs',
            email: 'noreply@traineesinonderwijs.nl'
        },
        subject: 'Een test mail'
    },
    body: {
        locals: {
            title: 'Een test mail',
            name: 'Remi',
            body: 'Dit is een test mail.',
            link: new URL('https://google.com'),
            sender: 'Het team van Trainees in onderwijs',
            closing: 'Met vriendelijke groet',
            buttonTxt: 'Klik op mij!',
            preHeader: 'Om te kijken of hij goed aankomt!',
            aanhef: 'Beste',
            note: 'De kleine lettertjes'
        }
    }
})

// Send email from template
mailer.send({
    config: {
        theme: 'traineesinonderwijs',
        template: 'magic_auth',
    },
    head: {
        to: 'remihuigen@gmail.com',
    },
    body: {
        locals: {
            name: 'Remi',
            link: new URL('https://google.com'),
        }
    }
})

Types

// Options for creating a new Mailer class
interface MailerOptions {
    config: MailerConfig
}

// Mailgun configuration
interface MailerConfig {
    MAILGUN_API_KEY: string
    MAILGUN_HOST: string
}


// Payloads for sending email. Can either be Clean or Template
type EmailPayload = CleanEmailPayload | TemplateEmailPayload

interface CleanEmailPayload {
    config: {
        theme: App
    }
    head: {
        to: string | string[]
        from: {
            name: string
            email: string
        }
        subject: string
    }
    body: {
        locals: TemplateLocals
        data?: TableData
    }
}

interface TemplateEmailPayload {
    config: {
        theme: App
        template: EmailTemplate
    }
    head: {
        to: string | string[]
    }
    body: {
        locals: {
            name?: string
            link: URL
        }
    }
}


// Other types used
type App = 'onderwijsloket' | 'traineesinonderwijs' | 'voorbereiden' | 'hulpvoordeklas'
type EmailTemplate = 'confirm_account' | 'welcome_user' | 'reset_password' | 'magic_auth'
type TemplateLocals = {
    title: string
    name?: string
    body: string
    link: null | URL
    sender: string
    closing: string
    buttonTxt: string
    preHeader: string
    aanhef: string
    note?: string
}
type TableData = Array<{label: string, value: string}>

Developing this package

• The main branch is used as the default, and up to date branch. You can add new branches to develop specific features
• When a new layer version is ready for production, run npm version to bump your package version. Then run:

npm run release --tag=$latestVersion --notes="$releaseMessage"              #(or npm run prerelease with the same flags)

That's it! Happy coding 🙂