sls-helper-plugin-janis

A Serverless Helper plugin to add custom helpers for Janis Commerce

Usage no npm install needed!

<script type="module">
  import slsHelperPluginJanis from 'https://cdn.skypack.dev/sls-helper-plugin-janis';
</script>

README

Serverless Helper Plugin JANIS

A plugin for JANIS Commerce to use with the Serverless Helper Framework.

npm version Build status Coverage Status

Helpers

base

Used to implement a base service with minimal setup

Option Type Description Attributes Default value
serviceCode string The service name in lowercase dash separated Required
servicePort number The service port Required
apiSecrets Object A mapping of stages to Service API Secret undefined

Some properties of the initial configuration have a new special meaning:

package.include and package.includeOnly

package.exclude and package.excludeOnly

package.plugins and package.pluginsOnly

This properties (if present in the initial service configuration) have the following behavior:

  • package.include, package.exclude and plugins will be appended to the hooks defaults
  • package.includeOnly, package.excludeOnly and pluginsOnly will replace entirely the hooks defaults

templates

Used to implement Lambda APIs requests and response templates as custom props

No options

authorizers

Used to implement APIs authorizers as custom props

Option Type Description Attributes Default value
accountId string Indicates the AWS account ID where the authorizers are deployed Required

cors

Used to implement APIs CORS configuration as custom props

If options is undefined or set to true it will use the default CORS config for every property. You can also customize or override every property:

Option Type Description Default value
replace boolean Indicates whether it should replace the CORS properties or merge then with the default false
origins array<string> An array of allowed origins ['*']
headers array<string> An array of allowed headers See below
allowCredentials boolean Indicates whether the credentials header should be set true
maxAge number The time in seconds thar CORS headers should be cached 600

CORS Default headers:

[
    'authorization',
    'content-type',
    'janis-api-key',
    'janis-api-secret',
    'janis-client',
    'janis-service',
    'janis-entity',
    'x-api-key',
    'x-janis-page',
    'x-janis-page-size'
]

api

Used to implement a custom API

Option Type Description Attributes Default value
path string The API path Required
method string The API HTTP Method 'get'
methodName string The JANIS API Method Enum<list, get, post, put, patch, delete> Defaults to same value of method option
handler string The lambda handler path and function 'src/lambda/RestApi/index.handler'
caching boolean Set to true to enable cache false
cors boolean object Set to true to enable services default CORS, or configure as an object as explained in CORS to customize the API CORS
queryParameters object A key value to map query string parameters to a boolean indicating if it's required or not
requestTemplates object A key value to map content types to request mapping headers. By default only application/json is enabled (Docs)
requestHeaders object A key value to map headers to a boolean indicating if it's required or not
authorizer string The name of the authorizer
timeout number The function timeout in seconds
package.include array[string] The List of paths of files to include
functionRawProps object Custom properties to set in the function configuration
eventRawProps object Custom properties to set in the event configuration

apiList, apiGet, apiPost and apiPut

Used to implement JANIS CRUD APIs.

Option Type Description Attributes Default value
entityName string The entity name Required
handler string The lambda handler path and function 'src/lambda/RestApi/index.handler'
path string The API path /[entity-name] (for apiList and apiPost) or /[entity-name]/{id} (for apiGet and apiPut)
caching boolean Set to true to enable cache false
cors boolean object Set to true to enable services default CORS, or configure as an object as explained in CORS to customize the API CORS
queryParameters object A key value to map query string parameters to a boolean indicating if it's required or not
requestTemplates object A key value to map content types to request mapping headers. By default only application/json is enabled (Docs)
requestHeaders object A key value to map headers to a boolean indicating if it's required or not
authorizer string The name of the authorizer
timeout number The function timeout in seconds
package.include array[string] The List of paths of files to include
functionRawProps object Custom properties to set in the function configuration
eventRawProps object Custom properties to set in the event configuration

eventListener

Used to implement JANIS Events listeners

Option Type Description Attributes Default value
serviceName string The service name Required
entityName string The entity name Required
eventName string The event name Required
mustHaveClient boolean Indicates if authorizer must validate that client or not false
listenersDirName string Indicates the path where the event listener files are placed 'event-listeners'
authorizer string The name of the authorizer If not set, it defaults to ServiceAuthorizer or ServiceNoClientAuthorizer based on the value of mustHaveClient
package.include array[string] The List of paths of files to include
timeout number The function timeout in seconds

dbConfig

(since 3.1.0)

Used to implement JANIS Database config as secret with an auto-generated password

Option Type Description Attributes Default value
secret string | object The secret content as an object or a JSON stringified object Required
secretName string The secret name 'janis/${self:custom.serviceCode}/${self:custom.stage}/db-config'
description string The secret description 'Database config secret for janis ${self:custom.serviceCode} ${self:custom.stage}'
passwordKey string The property name where the password will be generated 'password'
passwordLength number The generated password length 40

stateMachine

(since 4.3.0)

Used to implement AWS State Machines

Option Type Description Attributes Default value
name string The name of the state machine Required
definition object The definition of the state machine. See more Step Functions Required

It will automatically include the serverless-step-functions plugin.

It also defines 2 properties in the custom namespace:

  • custom.machines.{MachineName}.arn: The State Machine ARN
  • custom.machines.{MachineName}.name: The State Machine Name

Important: The {MachineName} in the custom.machines path will replaced be the name property converted to PascalCase. For example, if the following hook is configured

['janis.stateMachine', {
    name: 'my-super-machine',
    definition: myDefinition
}]

The following custom props will be set: custom.machines.MySuperMachine.arn and custom.machines.MySuperMachine.name

Examples

Basic Service with one CRUD operation set and an event listener

// serverless.js

'use strict';

const { helper } = require('sls-helper'); // eslint-disable-line

module.exports = helper({
    hooks: [

        ['janis.base', {
            serviceCode: 'my-service',
            servicePort: 5000,
            apiSecrets: {
                beta: 'foo',
                qa: 'bar',
                prod: 'baz'
            }
        }],

        'janis.templates',

        ['janis.authorizers', {
            accountId: '012345678910'
        }],

        'janis.cors',

        ['janis.api', {
            path: '/hello-world',
            authorizer: 'NoClientAuthorizer',
            cors: true
        }],

        ['janis.apiList', {
            entityName: 'product',
            authorizer: 'FullAuthorizer',
            cors: true
        }],

        ['janis.apiGet', {
            entityName: 'product',
            authorizer: 'FullAuthorizer',
            cors: true
        }]

        ['janis.apiPost', {
            entityName: 'product',
            authorizer: 'FullAuthorizer',
            cors: true
        }],

        ['janis.apiPut', {
            entityName: 'product',
            authorizer: 'FullAuthorizer',
            cors: true
        }],

        ['janis.apiList', {
            entityName: 'otherEntity',
            authorizer: 'FullAuthorizer',
            cors: {
                origins: ['*'], // Open to every origin
                allowCredentials: false
            }
        }],

        ['janis.eventListener', {
            serviceName: 'catalog',
            entityName: 'product',
            eventName: 'created',
            mustHaveClient: true
        }],

        ['janis.stateMachine', {
            name: 'StateMachineName',
            definition: {
                Comment: 'State Machine Comment',
                StartAt: 'WaitForCall',
                States: {
                    WaitForCall: {
                        Type: 'Wait',
                        SecondsPath: '$.body.wait',
                        Next: 'Finish'
                    }
                }
            }
        }]

    ]
}, {});