HSI-SDK

HSI SDK includes functions for calculations

Installation

npm install heeros/hsi-sdk

Releasing & building

1. Run npm run build:dist to bundle the sources into fresh distributions
2. PR the built distributions & merge to main branch
3. From the top of the main branch, execute

npm version <patch|minor|major> && git push && git push --tags

Structure & importing

The library provides 2 different modules for importing:

• hsi-sdk --> module that doesn't expect any dependencies to AWS (fits for client side)
• hsi-sdk/backend --> module that expects aws-sdk as a dependency (fits for backend side)

Depending on your use case, import/require either of the modules.

Components

Serializer

Module providing functions to serialize/de-serialize provided supported values as base64 data. For more in-depth details on how to use, see the written unit tests.

Can be used for example, to "stringify" the LastEvaluatedKey returned from DynamoDb for more convenient usage in the client side.

Usage

const { serializer } = require('hsi-sdk')
const serializedData = serializer.encode('foobar') // from string to token
const originalData = serializer.decode(serializedData, 'string') // from token to string

DynamoDB

QueryBuilder

Helper function, to provide functional API for generating DynamoDB queries. For more in-depth details on how to use, see the written unit tests in the test/lib/dynamodb/query-builder.test.js

Usage

const { dynamodb } = require('hsi-sdk')
const query = dynamodb.QueryBuilder()
      .fromTable('some-table')
      .fromIndex('some-index')
      .byKey({ zoo: 'some-key', jar: 'some-sort-key' }, { jar: { queryType: 'range' } }) // second arg provided, to configure expression
      .filterBy({
          foo: 'foo-val',
          bar: 'bar-val',
          ruta: { baga: 'baga-val' }
        },
        { foo: { queryType: 'lt' }, 'ruta.baga': { queryType: 'gt' }
      })
      .withExclusiveStartKey('some-starting-key')
      .withLimit(5)
      .includeAttributes(['foo', 'bar'])
      .build()

Filters

Module providing helper functionality for generating filter expressions

getFilterExpression

Usage

const { dynamodb: { filters } } = require('hsi-sdk')
const res = filters.getFilterExpression({ foo: 'bar', zoo: 'jar' })

// res equals:
/*
{
    filterExpression: '#foo = :foo and #zoo = :zoo',
    expressionAttributeNames: {
        '#foo': 'foo',
        '#zoo': 'zoo'
    },
    expressionAttributeValues: {
        ':foo': 'bar',
        ':zoo': 'jar'
    }
}
*/

Authorization

authorizedResource

This function expects to receive object containing Lambda API handlers & performs authorization checks for each based on provided parameters.

The argument object expects the following properties:

• apiHandlers - Object containing the API handlers
• subjects - Array of subjects describing the target contexts of the authorization
• scopeResolver - Optional promise returning function, to provide ability to resolve the possible scope for the authorization (ie. tt/la code)
• errorHandler - Optional function to handler authorization errors, ie. you can pass the error.throw* functions from the lambda-sdk here

Usage

const { authorization } = require('hsi-sdk')
const { error } = require('lambda-sdk')

const create = (params, event) => 'some handler responding to POST'

const authorizedHandlers = authorization.authorizedResource({
  apiHandlers: { create },
  subjects: ['settings'],
  scopeResolver: async (params) => 'for-example-some-resolved-ttla-combo',
  errorHandler: error.throwForbidden
})

States

States module includes functions that are dependant on resource statuses.

getRestrictions

This function accepts a status as an argument & returns an object illustrating possible restrictions related to the status (ie. whether certain fields should be read-only in the specified status).

The object returned follows following structure:

{
  _all: { readOnly: true },
  dueDate: { readOnly: false },
  noteDate: { readOnly: false },
  'product.domesticAccountNumber': { readOnly: false },
  'product.vat.code': { readOnly: false },
  'product.accountingObjectList': { readOnly: false }
}

The above example translates to:

1. set all fields as "read-only"
2. exclude dueDate & set it as editable
3. exclude noteDate & set it as editable
4. exclude product.domesticAccountNumber & set it as editable
5. exclude product.vat.code & set it as editable
6. exclude product.accountingObjectList & set it as editable

The property names are designed to follow dot-notation in complex fields, so they are easier to map in client side projects to form field names. However, fields containing arrays still require explicit handling.