logo

tests codecov license npm npm

Cloud Native Notifications Library

Airhorn makes it easy to send SMS, SMTP, Webhooks, and mobile push notifications easily using templates through your standard cloud providers. We focused on making it cloud native by default (using cloud services).

Table of Contents

Features

Gettign Started

To get started with Airhorn, you can install the package via npm:

npm install airhorn

Then, you can use the library in your code:

import { createAirhorn, AirhornProviderType } from 'airhorn';

const airhorn = new createAirhorn({
    TEMPLATE_PATH: './your-template-path',
    DEFAULT_TEMPLATE_LANGUAGE: 'en',
    SENDGRID_API_KEY: 'YOUR_SEND_GRID_API_KEY',
});
const data = {
    // your data to render the template goes here
}

airhorn.send('me@you.com', 'no-contact@company.com', 'template-name', AirhornProviderType.SMTP, data, 'en');

Library API

send()

The send() function, located in airhorn.ts, is used to send notifications. It accepts the following parameters:

sendSMTP()

The sendSMTP() function, located in airhorn.ts, is used to send SMTP notifications. It accepts the following parameters:

sendSMS()

The sendSMS() function, located in airhorn.ts, is used to send SMS notifications. It accepts the following parameters:

sendWebhook()

The sendWebhook() function, located in airhorn.ts, is used to send Webhook notifications. It accepts the following parameters:

sendMobilePush()

The sendMobilePush() function, located in airhorn.ts, is used to send Mobile Push notifications. It accepts the following parameters:

options

The AirhornOptions enables you to configure the settings of Airhorn. It accepts the following parameters:

These settings can be overridden by passing them in when you create a new instance of Airhorn:

const airhorn = new createAirhorn({
    TEMPLATE_PATH: './templates',
    DEFAULT_TEMPLATE_LANGUAGE: 'en',
    TWILIO_SMS_ACCOUNT_SID: 'YOUR TWILIO ACCOUNT SID',
    TWILIO_SMS_AUTH_TOKEN: 'YOUR TWILIO AUTH TOKEN',
    TWILIO_SENDGRID_API_KEY: 'YOUR SENDGRID API KEY',
    AWS_SES_REGION: 'YOUR AWS SES REGION',
    AWS_SMS_REGION: 'YOUR AWS SMS REGION',
    AWS_SNS_REGION: 'YOUR AWS SNS REGION',
    FIREBASE_CERT: 'YOUR FIREBASE CERTIFICATE',
    TEMPLATE_PROVIDER: 'YOUR TEMPLATE PROVIDER'
});

Templates

This library supports the use of templates to easily send formatted messages to different providers. Sample templates can be found in test/templates within the subdirectories cool-multi-lingual, generic-template-foo, and multiple-types-bar.

Language Localization

With templates, users can easily send messages in different languages. A sample architecture for language localized templates can be found in the cool-multi-lingual directory within test/templates. This directory contains folders for English and Spanish language codes, 'en' and 'es' respectively. Each of these directories contains SMS, SMTP, and Webhook templates in the appropriate language. To send notifications in a specific language, users can simply provide the appropriate languageCode parameter to the send() function.

Template Overrides

When looking at the sample templates, we can see that some of them support word substitution. For example, the generic SMTP template looks like this:

<p>Hello {{ firstName }} {{ lastName }}</p>
<p>Your email is {{ email }} and this is a generic template</p>

To substitute the appropriate text for firstName, lastName, and email, users can provide the appropriate data to the send() function. This data is then passed to the template and rendered automatically.

Template Providers (In Memory, MongoDB, Postgres)

By default Airhorn uses an in-memory provider called MemoryTemplateProvider. This is great for testing and quick use cases. Which means that you can load your templates into memory and use then. This is done when you call createAirhorn() with the TEMPLATE_PATH set.

import { createAirhorn } from 'airhorn';
const airhorn = new createAirhorn({ TEMPLATE_PATH: './your-template-path' });

If you want to use MongoDB or Postgres you can use the MongoTemplateProvider or PostgresTemplateProvider. This is great for production and long running services.

import { createAirhorn, MongoTemplateProvider } from 'airhorn';

const airhorn = new createAirhorn({
    TEMPLATE_PATH: './your-template-path',
    TEMPLATE_PROVIDER: new MongoTemplateProvider('mongodb://localhost:27017', 'airhorn')
});

You can also do it by just passing in the uri note that the other options will be set to the defaults. :

import { createAirhorn } from 'airhorn';

const airhorn = new createAirhorn({
    TEMPLATE_PATH: './your-template-path',
    TEMPLATE_PROVIDER: 'postgres://localhost:5432/airhorn'
});

Once you load a specific provider you will want to sync your templates to the provider. This is done using the syncTemplatesToAirhorn function.

import { syncTemplatesToAirhorn, createAirhorn } from 'airhorn';

const airhorn = new createAirhorn({
    TEMPLATE_PATH: './your-template-path',
    TEMPLATE_PROVIDER: 'postgres://localhost:5432/airhorn'
});

await syncTemplatesToAirhorn('./your-template-path', airhorn);

File System Templates

In most cases we want to use the file system to store our templates for all the benefits of gitops and versioning. We have added good support for loading templates from the file system based on the following structure:

templates
├── cool-multi-lingual
│   ├── en
│   │   ├── sms.hbs
│   │   ├── smtp.hbs
│   │   └── webhook.hbs
│   └── es
│       ├── sms.hbs
│       ├── smtp.hbs
│       └── webhook.hbs
├── generic-template-foo
│   ├── sms.hbs
|   ├── smtp.hbs
|   └── webhook.hbs

In this example you can see that we have the template name cool-multi-lingual and then the language code en for English. Then we have the type of template sms, smtp, and webhook. This is the structure that we use to load templates from the file system.

If you do not need to support multiple languages you can just have the template name and the type of template like the example of generic-template-foo.

Examples for using this library

This library can be used to easily send a variety of notifications. In this section, we'll cover how to implement some simple use cases.

Sending a simple email

Using the send function, we can email 'john@doe.org' from 'hello@testing.com' using the generic template 'generic-template-foo'. We'll also use the provider type AirhornProviderType.SMTP to indicate that we're sending an email:

import { createAirhorn, AirhornProviderType } from 'airhorn';
const airhorn = new createAirhorn({ TEMPLATE_PATH: './your-template-path' });
await airhorn.send('john@doe.org', 'hello@testing.com', 'generic-template-foo', AirhornProviderType.SMTP);

Sending a simple webhook

Here, we'll send a simple webhook to the URL 'https://mockhttp.org/post':

const airhorn = new createAirhorn({ TEMPLATE_PATH: './your-template-path' });
airhorn.send('https://mockhttp.org/post', 'foo', 'bar', AirhornProviderType.WEBHOOK);

Using multiple providers

In this example, we'll send a message using multiple email providers:

  1. Add in the AWS SES configuration
  2. Add in the Sendgrid configuration
  3. Send the message and it will randomly balance between the two providers.
const airhorn = new createAirhorn({
        TEMPLATE_PATH: './your-template-path',
        AWS_SES_REGION = 'us-east-1',
        TWILIO_SENDGRID_API_KEY = 'SENDGRID_API_KEY'
	});

await airhorn.send('john@doe.org', 'hello@testing.com', 'generic-template-foo', AirhornProviderType.SMTP);

Supported Cloud Service Providers

This library supports sending notifications via email, SMS, and Mobile Push for the following providers:

In this section, we'll describe how to use each of these notification services.

Email providers

This library supports sending emails via AWS SES and Twilio Sendgrid.

AWS SES

After configuring your system to use AWS SES, you can easily use airhorn to send emails. In this example, we'll email 'john@doe.org' from 'hello@testing.com' using the email template 'generic-template-foo'. We'll list the provider type as AirhornProviderType.SMTP to indicate that we're sending an email:

const airhorn = new createAirhorn({
        TEMPLATE_PATH: './your-template-path',
        AWS_SES_REGION = 'us-east-1',
	});
await airhorn.send('john@doe.org', 'hello@testing.com', 'generic-template-foo', AirhornProviderType.SMTP);

Twilio Sendgrid

To send emails via Twilio Sendgrid, first update the TWILIO_SENDGRID_API_KEY value via AirhornOptions. Then, we can use the same syntax as above to send an email through Twilio Sendgrid:

const airhorn = new createAirhorn({
        TEMPLATE_PATH: './your-template-path',
        TWILIO_SENDGRID_API_KEY = 'SENDGRID_API_KEY'
	});
await airhorn.send('john@doe.org', 'hello@testing.com', 'generic-template-foo', AirhornProviderType.SMTP);

SMS providers

This library supports sending SMS using AWS SMS and Twilio.

AWS SMS

Once your system is configured to use AWS SMS, you can send SMS notifications through AWS SMS. In this example, we'll send the notification to the phone number '5555555555' from the number '5552223333' with the raw text data 'Test message text'. Then, we'll list the provider type as AirhornProviderType.SMS.

const airhorn = new createAirhorn({
        TEMPLATE_PATH: './your-template-path',
        AWS_SMS_REGION = 'us-east-1',
    });
await airhorn.send('5555555555', '5552223333', 'Test message text', AirhornProviderType.SMS);

Twilio SMS

To send SMS notifications via Twilio SMS, first update the TWILIO_SMS_ACCOUNT_SID and the TWILIO_SMS_AUTH_TOKEN values via the AirhornOptions as shown below. Then, we can send an SMS notification using the same syntax as above:

const airhorn = new createAirhorn({
        TEMPLATE_PATH: './your-template-path',
        TWILIO_SMS_ACCOUNT_SID = 'TWILIO_SMS_ACCOUNT_SID',
        TWILIO_SMS_AUTH_TOKEN = 'TWILIO_SMS_AUTH_TOKEN'
    });
await airhorn.send('5555555555', '5552223333', 'Test message text', AirhornProviderType.SMS);

Mobile push providers

This library supports sending Mobile Push notifications using AWS SNS and Google Firebase.

AWS SNS

To use AWS SNS you will need to create a new SNS application in the AWS console and integrate the AWS SNS SDK into your application.

  1. Obtain the credentials and device token for the mobile platforms that you want to support.
  2. Use the credentials to create a platform application object (PlatformApplicationArn) using Amazon SNS. For more information, see Creating a platform endpoint.
  3. Use the returned credentials to request a device token for your mobile app and device from the mobile platforms. The token you receive represents your mobile app and device.
  4. Use the device token and the PlatformApplicationArn to create a platform endpoint object (EndpointArn) using Amazon SNS. For more information, see Creating a platform endpoint.

Then, you can send the push message to the device endpoint using airhorn:

const airhorn = new createAirhorn({
        TEMPLATE_PATH: './your-template-path',
        AWS_SNS_REGION = 'us-east-1',
    });
await airhorn.send('endpointArn', '', 'generic-template-foo', AirhornProviderType.MOBILE_PUSH);

Firebase for Mobile Push

To use Firebase in your application, you will need to create a new project in the Firebase console and integrate the Firebase SDK according to the Firebase documentation.

In your Firebase Project Settings, go to the Service accounts tab to generate your private key as a json file and put the content of the file as FIREBASE_CERT environment variable.

Then, you can send the push message to the device endpoint using airhorn:

const airhorn = new createAirhorn({
        TEMPLATE_PATH: './your-template-path',
        FIREBASE_CERT = 'FIREBASE_CERT'
    });
await airhorn.send('endpointArn', '', 'generic-template-foo', AirhornProviderType.MOBILE_PUSH);

ESM and Node Version Support

This package is ESM only and tested on the current lts version and its previous. Please don't open issues for questions regarding CommonJS / ESM or previous Nodejs versions.

How to Contribute

Now that you've set up your workspace, you're ready to contribute changes to the airhorn repository you can refer to the CONTRIBUTING guide. If you have any questions please feel free to ask by creating an issue and label it question.

Setting up your Development Environment

To set up your development environment, you'll need the following dependencies:

Set up your firebase account and generate the firebase-cert.json file. Then, place the file in the root of the project. This is needed even for testing as mocking the firebase-admin is almost impossible. After that you should run the following commands:

npm i && npm run test:services:start && npm test

This will start the services needed for testing and run the tests.

To stop the services, you can run:

npm run test:services:stop

If you are using nvm you can run the following:

nvm use && npm i && npm run test:services:start && npm test

Licensing and Copyright

This project is MIT License © Jared Wray

Contributors

jaredwray chrisllontop jaytist jasonbaik osbornm

Latest's Releases

v4.1.4 March 06, 2025

What's Changed

Full Changelog: https://github.com/jaredwray/airhorn/compare/v4.1.3...v4.1.4

v4.1.3 February 06, 2025

What's Changed

Full Changelog: https://github.com/jaredwray/airhorn/compare/v4.1.2...v4.1.3

v4.1.2 January 05, 2025

What's Changed

Full Changelog: https://github.com/jaredwray/airhorn/compare/v4.1.1...v4.1.2

All Releases →