/fastify-aws-sns

Fastify plugin to AWS Simple Notification Service (AWS SNS) to coordinates and manages the delivery or sending of messages to subscribing endpoints or clients

Primary LanguageJavaScriptMIT LicenseMIT

fastify-aws-sns

js-standard-style CI workflow

Supports Fastify versions 4.x

fastify-aws-sns is plugins to communicate with Amazon Simple Notification Service (Amazon SNS), a web service that enables you to build distributed web-enabled applications. Applications can use Amazon SNS to easily push real-time notification messages to interested subscribers over multiple delivery protocols.

With AWS SNS publishers communicate asynchronously with subscribers by producing and sending a message to a topic, which is a logical access point and communication channel. Subscribers (web servers, email addresses, Amazon SQS queues, AWS Lambda functions) consume or receive the message or notification over one of the supported protocols (Amazon SQS, HTTP/S, email, SMS, AWS Lambda) when they are subscribed to the topic.

Install

npm i fastify-aws-sns

and setup AWS environments:

export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_DEFAULT_REGION=us-west-2

Custom Environments

  • AWS_TOPIC_NAME: AWS SNS Topic Name
export AWS_TOPIC_NAME=myTopic

Usage

Require fastify-aws-sns and register.

const fastify = require('fastify')()

fastify.register(require('fastify-aws-sns'))
fastify.listen({ port: 3000 })

Topic

To create, list, and delete Amazon SNS topics, and to handle topic attributes

Options Topics

Options Method Optional Default value Description
topic create yes process.env.AWS_TOPIC_NAME
topicArn list, del, getAttributes, setAttributes no
attributeName setAttributes no
attributeValue setAttributes no

fastify.snsTopics.create(options)

To create an Amazon SNS topic and return topicArn

fastify.snsTopics.create({
    topic: 'mySNSMessages'
}).then(result => {
    console.log(result)
}).catch(e => {
    console.error(e)
})

fastify.snsTopics.list(options)

to list all Amazon SNS topics

fastify.snsTopics.list({
    topicArn: 'xxx:xxxx:xxxxxx'
}).then(result => {
    console.log(result)
}).catch(e => {
    console.error(e)
})

fastify.snsTopics.del(options)

to delete an Amazon SNS topic

fastify.snsTopics.del({
    topicArn: 'xxx:xxxx:xxxxxx'
}).then(result => {
    console.log(result)
}).catch(e => {
    console.error(e)
})

fastify.snsTopics.getAttributes(options)

to retrieve attributes of an Amazon SNS topic

fastify.snsTopics.getAttributes({
    topicArn: 'xxx:xxxx:xxxxxx'
}).then(result => {
    console.log(result)
}).catch(e => {
    console.error(e)
})

fastify.snsTopics.setAttributes(options)

to set the mutable attributes of an Amazon SNS topic

fastify.snsTopics.setAttributes({
    topicArn: 'xxx:xxxx:xxxxxx',
    attributeName: 'xxxxxx',
    attributeValue: 'yyyyyy'
}).then(result => {
    console.log(result)
}).catch(e => {
    console.error(e)
})

Message

Publish messages from Amazon SNS to topic endpoints, emails, or phone numbers

Options Message

Options Method Optional Default value Description
topicArn publish no
message publish no

fastify.snsMessage.publish(options)

to publish a message to an Amazon SNS topic

fastify.snsMessage.publish({
    topicArn: 'xxx:xxxx:xxxxxx',
    message: 'my message'
}).then(result => {
    console.log(result)
}).catch(e => {
    console.error(e)
})

SubScriptions

Publish notification messages to Amazon SNS topics.

Options SubScriptions

Options Method Optional Default value Description
topicArn list, setByEMail, confirmSubscriptionByEMail, setByEndPoint, setByLambda no
topicSubscriptionArn unsubscribe no
email setByEMail, setByEMailJSON no
token confirmSubscriptionByEMail no
endPointArn setByEndPoint, setBySQS no
phoneNumber setBySMS no
roleArn setByFireHose no
endPoint setByHttp, setByHttps no
lambdaArn setByLambda no

fastify.snsSubscriptions.list(options)

to list all subscriptions to an Amazon SNS topic

fastify.snsSubscriptions.list({
    topicArn: 'xxx:xxxx:xxxxxx'
}).then(result => {
    console.log(result)
}).catch(e => {
    console.error(e)
})

fastify.snsSubscriptions.setByEMail(options)

to subscribe an email address so that it receives SMTP email messages from an Amazon SNS topic

fastify.snsSubscriptions.setByEMail({
    topicArn: 'xxx:xxxx:xxxxxx',
    email: 'giuseppe.zileni@gmail.com'
}).then(result => {
    // token to send confirmSubscriptionByEMail method
    console.log(result)
}).catch(e => {
    console.error(e)
})

fastify.snsSubscriptions.confirmSubscription(options)

to verify an endpoint owner's intent validating the token sent to the endpoint by a previous subscribe action

fastify.snsSubscriptions.confirmSubscription({
    token: 'xxx:xxxx:xxxxxx',
    topicArn: 'xxx:xxxx:xxxxxx'
}).then(result => {
    console.log(result)
}).catch(e => {
    console.error(e)
})

fastify.snsSubscriptions.setByEndPoint(options)

to subscribe a mobile application endpoint so it receives notifications from an Amazon SNS topic

fastify.snsSubscriptions.setByEndPoint({
    endPointArn: 'xxx:xxxx:xxxxxx',
    topicArn: 'xxx:xxxx:xxxxxx'
}).then(result => {
    console.log(result)
}).catch(e => {
    console.error(e)
})

fastify.snsSubscriptions.setByLambda(options)

to subscribe an AWS Lambda function so it receives notifications from an Amazon SNS topic

fastify.snsSubscriptions.setByLambda({
    lambdaArn: 'xxx:xxxx:xxxxxx',
    topicArn: 'xxx:xxxx:xxxxxx'
}).then(result => {
    console.log(result)
}).catch(e => {
    console.error(e)
})

fastify.snsSubscriptions.unsubscribe(options)

to unsubscribe an Amazon SNS topic subscription.

fastify.snsSubscriptions.unsubscribe({
    topicSubscriptionArn: 'xxx:xxxx:xxxxxx'
}).then(result => {
    console.log(result)
}).catch(e => {
    console.error(e)
})

fastify.snsSubscriptions.setByHttp(options)

to subscribe an HTTP Endpoint so it receives notifications from an Amazon SNS topic

fastify.snsSubscriptions.setByHttp({
    endPoint: 'http://www.myserver.com/',
    topicArn: 'xxx:xxxx:xxxxxx'
}).then(result => {
    console.log(result)
}).catch(e => {
    console.error(e)
})

fastify.snsSubscriptions.setByHttps(options)

to subscribe an HTTPs Endpoint so it receives notifications from an Amazon SNS topic

fastify.snsSubscriptions.setByHttps({
    endPoint: 'https://www.myserver.com/',
    topicArn: 'xxx:xxxx:xxxxxx'
}).then(result => {
    console.log(result)
}).catch(e => {
    console.error(e)
})

fastify.snsSubscriptions.setByFireHose(options)

to subscribe an AWS Kinesis Data FireHose so it receives notifications from an Amazon SNS topic

fastify.snsSubscriptions.setByFireHose({
    endPointArn: 'xxx:xxxx:xxxxxx',
    topicArn: 'xxx:xxxx:xxxxxx',
    roleArn: 'xxx:xxxx:xxxxxx'
}).then(result => {
    console.log(result)
}).catch(e => {
    console.error(e)
})

fastify.snsSubscriptions.setByEMailJSON(options)

to subscribe an email address to delivery of JSON-encoded message via SMTP that it receives from an Amazon SNS topic

fastify.snsSubscriptions.setByEMailJSON({
    topicArn: 'xxx:xxxx:xxxxxx',
    email: 'giuseppe.zileni@gmail.com'
}).then(result => {
    // token to send confirmSubscriptionByEMail method
    console.log(result)
}).catch(e => {
    console.error(e)
})

fastify.snsSubscriptions.setBySQS(options)

to subscribe an email address to delivery of JSON-encoded message to an Amazon SQS queue that it receives from an Amazon SNS topic

fastify.snsSubscriptions.setBySQS({
    endPointArn: 'xxx:xxxx:xxxxxx',
    topicArn: 'xxx:xxxx:xxxxxx'
}).then(result => {
    console.log(result)
}).catch(e => {
    console.error(e)
})

fastify.snsSubscriptions.setBySMS(options)

to subscribe an email address delivery of message via SMS to an phone number that it receives from an Amazon SNS topic

fastify.snsSubscriptions.setBySMS({
    phoneNumber: '353861230764',
    topicArn: 'xxx:xxxx:xxxxxx'
}).then(result => {
    console.log(result)
}).catch(e => {
    console.error(e)
})

SMS

Send text messages, or SMS messages, to SMS-enabled devices

Options SMS

Options Method Optional Default value Description
attributeName getAttributes no Attribute name
attributeType setAttributes yes 'Promotional' The type of SMS message that you will send by default
phoneNumber isNumber, publish no Phone Number in the E.164 phone number structure
message publish no Message to send

fastify.snsSMS.getAttributes(options)

to get the current SMS attributes in Amazon SNS

fastify.snsSMS.getAttributes({
    attributeName: 'xxxxxx'
}).then(result => {
    console.log(result)
}).catch(e => {
    console.error(e)
})

fastify.snsSMS.setAttributes(options)

to set the current SMS attributes in Amazon SNS:

  • Promotional – (Default) Noncritical messages, such as marketing messages. Amazon SNS optimizes the message delivery to incur the lowest cost.
  • Transactional – Critical messages that support customer transactions, such as one-time passcodes for multi-factor authentication. Amazon SNS optimizes the message delivery to achieve the highest reliability.
fastify.snsSMS.setAttributes({
    attributeType: 'Promotional'
}).then(result => {
    console.log(result)
}).catch(e => {
    console.error(e)
})

fastify.snsSMS.isNumber(options)

to check a phone number to see if it has opted out from receiving SMS messages

fastify.snsSMS.isNumber({
    phoneNumber: '353861230764'
}).then(result => {
    console.log(result)
}).catch(e => {
    console.error(e)
})

fastify.snsSMS.listNumbers()

to get a list of phone numbers that have opted out from receiving SMS messages

fastify.snsSMS.listNumbers().then(result => {
    console.log(result)
}).catch(e => {
    console.error(e)
})

fastify.snsSMS.publish(options)

to send an SMS message to a phone number

fastify.snsSMS.publish({
    message: 'my text message',
    phoneNumber: '353861230764'
}).then(result => {
    console.log(result)
}).catch(e => {
    console.error(e)
})

Acknowledgements

License

Licensed under MIT.