Airhorn is built to enable a more robust notification system. We focused on making it cloud native by default (using cloud services).
send()The send() function, located in airhorn.ts, is used to send notifications. It accepts the following parameters:
to (string): The address to send the message to. Based on the message provider, this address can be either a phone number, an email address, or a web address.from (string): The address of the sender of the message.templateName (string): The name of the template to use for the message.providerType (ProviderType): The type of message to be sent. ProviderType is an enum with the values SMTP, SMS, WEBHOOK, and MOBILE_PUSH.data (any): The information to pass to the message. This parameter is typically a data object or a string. The data can include the raw message to be sent, or it can be used to populate a message template.languageCode (string): The language code of the message template to be sent.configThe Config class, enables you to configure the settings of Airhorn. It accepts the following parameters:
TEMPLATE_PATH (string): The path where the notification system checks for templates. By default, this is set to './templates'DEFAULT_TEMPLATE_LANGUAGE (string): The default language code the notification system uses for localization, if a language code is not provided. By default, this is set to 'en' for English localization.ENVIRONMENT (string): The environment that the notification system uses to deploy messages. By default, this is set to 'development'TWILIO_SMS_ACCOUNT_SID (string): The ID of your Twilio SMS account. By default, this value is a null string.TWILIO_SMS_AUTH_TOKEN (string): The authentication token for your Twilio SMS account. By default, this value is a null string.TWILIO_SENDGRID_API_KEY (string): The API key for your Twilio SendGrid account. By default, this value is a null string.AWS_SES_REGION (string): For AWS, the endpoint region where an email is sent. By default, this value is a null string.AWS_SMS_REGION (string): For AWS, The endpoint region where an SMS is sent. By default, this value is a null string.AWS_SNS_REGION (string): For AWS, the endpoint region where a push notification is sent. By default, this value is a null string.FIREBASE_CERT (string): The certificate for sending push notifications through Google Firebase. By default, this value is a null string.These settings can be overridden by passing them in when you create a new instance of Airnorn:
const airhorn = new Airhorn({
TEMPLATE_PATH: './templates',
DEFAULT_TEMPLATE_LANGUAGE: 'en',
ENVIRONMENT: 'development',
TWILIO_SMS_ACCOUNT_SID: '',
TWILIO_SMS_AUTH_TOKEN: '',
TWILIO_SENDGRID_API_KEY: '',
AWS_SES_REGION: '',
AWS_SMS_REGION: '',
AWS_SNS_REGION: '',
FIREBASE_CERT: ''
});
});
You can also pass these settings via your process.env at the start of your application.
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.
By default, Config will look for templates at ./templates. However, this path can be manually adjusted if needed.
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.
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:
---
subject: Generic Hello
---
<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.
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.
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 ProviderType.SMTP to indicate that we're sending an email:
const airhorn = require('airhorn');
await airhorn.send('john@doe.org', 'hello@testing.com', 'generic-template-foo', ProviderType.SMTP);
Here, we'll send a simple webhook to the URL 'https://httpbin.org/post':
const airhorn = new Airhorn();
airhorn.send('https://httpbin.org/post', 'foo', 'bar', ProviderType.WEBHOOK);
In this example, we'll send a message using multiple email providers:
const airhorn = new Airhorn({
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', ProviderType.SMTP);
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.
This library supports sending emails via AWS SES and Twilio Sendgrid.
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 ProviderType.SMTP to indicate that we're sending an email:
const airhorn = new Airhorn({
AWS_SES_REGION = 'us-east-1',
});
await airhorn.send('john@doe.org', 'hello@testing.com', 'generic-template-foo', ProviderType.SMTP);
To send emails via Twilio Sendgrid, first update the TWILIO_SENDGRID_API_KEY value in config.ts. Then, we can use the same syntax as above to send an email through Twilio Sendgrid:
const airhorn = new Airhorn({
TWILIO_SENDGRID_API_KEY = 'SENDGRID_API_KEY'
});
await airhorn.send('john@doe.org', 'hello@testing.com', 'generic-template-foo', ProviderType.SMTP);
This library supports sending SMS using AWS SMS and Twilio.
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 ProviderType.SMS.
const airhorn = new Airhorn({
AWS_SMS_REGION = 'us-east-1',
});
await airhorn.send('5555555555', '5552223333', 'Test message text', ProviderType.SMS);
To send SMS notifications via Twilio SMS, first update the TWILIO_SMS_ACCOUNT_SID and the TWILIO_SMS_AUTH_TOKEN values via the options as shown below. Then, we can send an SMS notification using the same syntax as above:
const airhorn = new Airhorn({
TWILIO_SMS_ACCOUNT_SID = 'TWILIO_SMS_ACCOUNT_SID',
TWILIO_SMS_AUTH_TOKEN = 'TWILIO_SMS_AUTH_TOKEN'
});
await airhorn.send('5555555555', '5552223333', 'Test message text', ProviderType.SMS);
This library supports sending Mobile Push notifications using AWS SNS and Google Firebase.
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.
Then, you can send the push message to the device endpoint using airhorn:
const airhorn = new Airhorn({
AWS_SNS_REGION = 'us-east-1',
});
await airhorn.send('endpointArn', '', 'generic-template-foo', ProviderType.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 Airhorn({
FIREBASE_CERT = 'FIREBASE_CERT'
});
await airhorn.send('endpointArn', '', 'generic-template-foo', ProviderType.MOBILE_PUSH);
In this section of the documentation we will cover:
This package requires Node.js to run.
To contribute to this repository, start by setting up this project locally:
git clonenpm install command to install any dependencies.Now that you've set up your workspace, you're ready to contribute changes to the airhorn repository.
npm test command in the root directory.airhorn repository and go the Pull Requests tab.airhorn repository.If you need more information on the steps to create a pull request, you can find a detailed walkthrough in the Github documentation
FAQs
Cloud Notification Library
The npm package airhorn receives a total of 15 weekly downloads. As such, airhorn popularity was classified as not popular.
We found that airhorn demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Newly introduced telemetry in devenv 1.4 sparked a backlash over privacy concerns, leading to the removal of its AI-powered feature after strong community pushback.
Security News
TC39 met in Seattle and advanced 9 JavaScript proposals, including three to Stage 4, introducing new features and enhancements for a future ECMAScript release.
Security News
Deno 2.2 enhances Node.js compatibility, improves dependency management, adds OpenTelemetry support, and expands linting and task automation for developers.