tom ? is a backoffice for your projects, oriented for doing things like:
- Handle payments workflow ( create customers, subscribe to plans) using Stripe.
- Send notifications (email/Slack/Twitter/Telegram), even based on a template.
- Easy to extend & customize using Event System.
- Chainable actions, running them on series or parallel.
- Expose it over HTTP or as CLI.
Install
$ npm install tom-microservice
Usage
!> You can see a fully production ready example at tom-example.
You can consume tom ? from different ways.
as microservice
Just execute tom and the server will start:
To see details of a command use tom --help
Also declare it as part of your npm scripts:
{
"scripts": {
"start": "tom"
}
}
The microservice accepts command options in snake and camel case as body parameters.
from CLI
You can execute tom as CLI to resolve the same functionality than the microservice endpoint:
$ tom --command=notification.email --templateId=welcome --to=hello@kikobeats.com --subject='hello world'
To view details for a command at any time use tom --help
from Node.js
// First of all you need to declare a configuration file.
const config = {/* See configuration section */}
// Pass configuration file to `tom-microservice` module.
const tom = require('tom-microservice')(config)
// Now you can access `tom` commands
const { payment, email } = tom
Configuration
Loading your configuration
!> Combine with config for loading different settings based on environment.
All the tom ? actions are based on a configuration file.
You can define the configuration file via:
- A
.tomrcfile, written in YAML or JSON, with optional extensions: .yaml/.yml/.json/.js. - A
tom.config.jsfile that exports an object. - A
tomkey in your package.json file.
Just put your configuration in one of these places, tom ? will automatically load it.
Required configuration fields
!> Get a free email domain alias using improvmx.com or forwardemail.net.
The minimal configuration necessary is related with your company.
company:
name: microlink
site: microlink.io
link: https://microlink.io
logo: https://microlink.io/logo.png
email: hello@microlink.io
copyright: Copyright © 2018 Microlink. All rights reserved.
For the rest, tom ? will notify you on execution time if any specific configuration value is missing.
Event System
!> Event System is only supported with tom.config.js configuration file.
Every time tom ? execute a command successfully it will be emit an event:
// Register stats for payment processed
tom.on('payment:create', async data => {
const info = await sendAnalytics(data)
return info
})
The data received will be the last command execution output.
The events system are designed to allow you perform async actions.
If you return something, then it will be added into the final payload, that will be printed at the log level.
The events emitted are of 3 hierarchical types:
// An event emitted for a command under a category
tom.on('payment:create', sendAnalytics)
// An event emitted under a category
tom.on('payment', sendAnalytics)
// Any event
tom.on('*', sendAnalytics)
Commands
The commands define what things you can do with tom ?.
Every command has his own field at configuration.
payment
It creates new customer and subcribe them to previous declared product plans, using Stripe.
In addition, tom ? will fill useful customer metadata inforomation whetever is possible (such ass IP Address, country, region, VAT rate, currency code, etc.)
payment:create
POST
It handles are payment, expecting a Stripe Token, creating new a customer and subscribe it a previous created billing product.
Data Parameters
planId
Required
type: integer
A previously created Stripe plan identifier.
token
Required
type: Token
The token object generated by Stripe.
payment:update
POST
It will update the source update associated with a customer, based on a Stripe Token.
Data Parameters
customerId
Required
type: string
A previously created Stripe customer identifier.
token
Required
type: object
The token object generated by Stripe.
payment:session
POST
It validates a Stripe session previously created via Stripe Checkout.
Data Parameters
sessionId
Required
type: string
The Stripe session identifier.
payment:webhook
POST
It exposes an endpoint to be triggered by Stripe Webhook.
For using Stripe webhook you need to setup webhook in your account.
Click + Add Endpoint and the URL should the URL where tom ? is deployed end by payment/webhook e.g., tom.localtunnel.me/microlink.io/payment/webhook.
The events to send need to be at least contain checkout.session.completed.
If you want to test the webhook locally, you can use localtunnel to expose your local server.
The webhook signature will be checked to verify that the events were sent by Stripe.
notification
It sends notification using different providers and transporters.
notification:email
POST
It sends transactional emails based on templates defined.
Under non production scenario, you can use ethereal as transporter and it will be generate a preview of the email sent.
Data Parameters
templateId
type: string
If it is present, it will be generate text and html using the template.
text
The plain text content version of the email notification.
html
The HTML content version of the email notification.
from
type: string
default: config.email.template[templateId].from
The creator of the mail.
to
type: array
default: company.email
The recipients of the mail.
cc
type: array
default: config.email.template[templateId].cc
Carbon copy recipients of the mail.
bcc
type: array
default: config.email.template[templateId].cc
Blind carbon copy recipients of the mail.
subject
type: string
default: config.email.template[templateId].subject
The email subject.
attachments
type: array
default: req.body.attachments
An array of attachment objects (see nodemailer#attachments for details).
Attachments can be used for embedding images as well.
notification:slack
POST
It sends a Slack message.
Data Parameters
webhook
Required
type: string
The Incoming Webhook for Slack used for sending the data.
templateId
Type: string
If it is present, it load a previous declared template.
text
type: string
The text of the message.
It supports some specific formatting things, see formatting text in messages.
blocks
type: object
The block structure for creating rich messages, see message layouts.
You can compose blocks structures quickly using Slack Block Kit Builder.
notification:telegram
POST
It sends a telegram message to the specified chat id.
Data Parameters
templateId
type: string
If it is present, it will be generate text using the template.
chatId
Required
type: number
The Telegram chat id that will receive the message.
text
Required
type: string
The message that will be sent.
notification:twitter
POST
It sends a notification using Twitter as provider.
Data Parameters
templateId
type: string
If it is present, it will be generate text using the template.
text
Required
type: string
The text of the message.
type
Required
type: string
Choose one of the different ways the message can be send.
The types availables are tweet or dm.
recipientId
type: string
It defines the user that will be receive the message.
It is only necessary on dm mode.
batch
It runs more than one command in the same action.
batch:parallel
POST
It runs all the commands in paralell, without waiting until the previous function has completed.
If any of the commands throw an error, the rest continue running.
Data Parameters
The commands should be provided as a collection:
[
{
"command": "notification.email",
"templateId": "welcome",
"to": "hello@kikobeats.com"
}, {
"command": "telegram",
"templateId": "welcome",
"to": "hello@kikobeats.com",
"chatId": 1234
}
]
The field command determine what command should be used while the rest of parameters provided will be passed through the command.
batch:series
POST
It runs all the commands in series, each one running once the previous function has completed, each passing its result to the next.
If any of the commands throw an error, no more functions are run.
Data Parameters
The commands should be provided as a collection:
[
{
"command": "notification.email",
"templateId": "welcome",
"to": "hello@kikobeats.com"
}, {
"command": "telegram",
"templateId": "welcome",
"to": "hello@kikobeats.com",
"chatId": 1234
}
]
The field command determine what command should be used while the rest of parameters provided will be passed through the command.
Environment Variables
Some credentials could be provided as environment variables as well
general
TOM_ALLOWED_ORIGIN
Type: boolean, string, regex, array
Default: '*'
It configures the Access-Control-Allow-Origin CORS.
See cors for more information.
TOM_API_KEY
Type: string
Default: undefined
When you provide it, all request to tom ? needs to be authenticated using x-api-key header and the value provided.
You can use randomkeygen.com for that.
TOM_PORT
Type: number
Default: 3000
The port to uses for run the HTTP microservice.
payment
TOM_STRIPE_KEY
Type: string
Default: config.payment.stripe_key
The Stripe key associated with your account.
TOM_STRIPE_WEBHOOK_SECRET
Type: string
Default: config.payment.stripe_webhook_secret
The Stripe Webhook signature for verifying events were sent by Stripe.
notification
TOM_EMAIL_USER
Type: string
Default: config.email.transporter.auth.user
Your SMTP authentication user credential.
TOM_EMAIL_PASSWORD
Type: string
Default: config.email.transporter.auth.password
Your SMTP authentication password credential.
TOM_TWITTER_CONSUMER_KEY
Type: string
Default: config.twitter.consumer_key
Your consumer secret key from Twitter authentication credentials.
TOM_TWITTER_CONSUMER_SECRET
Type: string
Default: config.twitter.consumer_secret
Your consumer secret Twitter authentication credentials.
TOM_TWITTER_ACCESS_TOKEN_SECRET
Type: string
Default: config.twitter.access_token_secret
Your access token secret from Twitter authentication credentials.
TOM_TWITTER_ACCESS_TOKEN
Type: string
Default: config.twitter.access_token
Your access token from Twitter authentication credentials.
TOM_TELEGRAM_KEY
Type: string
Default: config.telegram.token
Your Telegram @BotFather token.
License
tom © Kiko Beats, Released under the MIT License.
Spaceman logo by Nook Fulloption from the Noun Project.
Authored and maintained by Kiko Beats with help from contributors.
kikobeats.com · GitHub @Kiko Beats · Twitter @Kikobeats