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.
$ npm install tom-microserviceYou can consume tom 🐶 from different ways.
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.
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
// 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!> Use config to load different configurations based on environments.
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.
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.This information will be used across all the commands.
!> 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)The commands define what things you can do with tom 🐶.
Every command has his own field at configuration.
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.)
POST
It handles are payment, expecting a Stripe Token, creating new a customer and subscribe it a previous created billing product.
Required
type: integer
A previously created Stripe plan identifier.
Required
type: Token
The token object generated by Stripe.
POST
It will update the source update associated with a customer, based on a Stripe Token.
Required
type: string
A previously created Stripe customer identifier.
Required
type: object
The token object generated by Stripe.
POST
It validates a Stripe session previously created via Stripe Checkout.
Required
type: string
The Stripe session identifier.
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.
It sends notification using different providers and transporters.
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.
type: string
If it is present, it will be generate text and html using the template.
The plain text content version of the email notification.
The HTML content version of the email notification.
type: string
default: config.email.template[templateId].from
The creator of the mail.
type: array
default: company.email
The recipients of the mail.
type: array
default: config.email.template[templateId].cc
Carbon copy recipients of the mail.
type: array
default: config.email.template[templateId].cc
Blind carbon copy recipients of the mail.
type: string
default: config.email.template[templateId].subject
The email subject.
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.
POST
It sends a Slack message.
Required
type: string
The Slack webhook endpoint for sending the data.
Type: string
If it is present, it will be generate text using the template.
Required
type: string
The text of the message.
type: object
The message attachments, you can find more information at Slack Documentation
POST
It sends a telegram message to the specified chat id.
type: string
If it is present, it will be generate text using the template.
Required
type: number
The Telegram chat id that will receive the message.
Required
type: string
The message that will be sent.
POST
It sends a notification using Twitter as provider.
type: string
If it is present, it will be generate text using the template.
Required
type: string
The text of the message.
Required
type: string
Choose one of the different ways the message can be send.
The types availables are tweet or dm.
type: string
It defines the user that will be receive the message.
It is only necessary on dm mode.
It runs more than one command in the same action.
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.
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.
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.
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.
Credentials could be provided as environment variables as well
Type: boolean|string|regex|array
Default: '*'
It configures the Access-Control-Allow-Origin CORS.
See cors for more information.
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.
Type: number
Default: 3000
The port to uses for run the HTTP microservice.
Type: string
Default: config.payment.stripe_key
The stripe key of your account.
Type: string
Default: config.email.transporter.auth.user
Your SMTP authentication user credential.
Type: string
Default: config.email.transporter.auth.password
Your SMTP authentication password credential.
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