README.md

sms-service

A simple way to send SMS text messages.

Prerequisites

1. AWS IAM User Credentials for programmatic access

   This module utilizes Amazon SNS for sending SMS messages. As such, this will require an AWS account and an IAM User with programmatic access keys. The aws-sdk has a number of options for setting AWS credentials. Refer to the official AWS documentation for further instruction.

2. IAM Policy for SNS

   The AWS IAM user will require proper IAM policy permissions to publish SMS messages. The SMS publish feature in SNS does not (for now) have a unique AWS resource, and thus there are no ideal ways to lock down access control. However, here is a sample policy allowing access to only publish SMS messages while denying access to publish on topics, applications, and push notifications:

    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Deny",
                "Action": [
                    "sns:Publish"
                ],
                "Resource": "arn:aws:sns:*:*:*"
            },
            {
                "Effect": "Allow",
                "Action": [
                    "sns:Publish"
                ],
                "Resource": "*"
            }
        ]
    }

   If you know the set of recipients before hand, you can further tighten access control permissions by listing specific phone numbers in the last Resource node.

Installation

1. Install via npm:

   npm install sms-service

Usage

Within your javascript application, you can use the SMSService to send SMS text messages:

//initialize
const sms = require('sms-service');
const smsService = new sms.SMSService();


async smsService.sendSMS('15555555555','hello from sms-service!');

The phoneNumber format must be in E.164 format. For example, a USA based number of 555-555-5555, the service would require 15555555555. Refer to this guide for additional information.

Debug Logging

Debug logging is provided by debug, and can be turned on setting the environment variable DEBUG.

PowerShell Example:

$env:DEBUG = "*"

Bash:

export DEBUG=*

Contributing

Automated Publish

1. Utilizing GitHub Actions, after committing / merging changes into master, simply use npm version command to force a release on GitHub and trigger the workflow:

   npm version 1.1.4 -m "Upgrade to %s for reasons"

Manual Publish

1. After merging feature branch changes back into master, follow semver and bump git version tag:

   git tag -a 1.X.X -m "adding version XXX"

2. bump npm module version:

   npm version from-git

   Note: npm version also will push all git commits and tags to origin. This was configured in the package.json scripts:

       "version": "npm run format && git add -A src",
       "postversion": "git push && git push --tags"

3. publish new release to npm:

   npm publish