README

@auvious/common / Exports

auvious common

This repository is a fork of the auvious-api-template repository. Every Auvious API module should be a fork of that repo and should frequently pull updates.

That way common changes can be pushed on the template repo and pulled from every child repo with ease.

---

Includes common source code to be used by the api modules.

• http client / api resource (over axios)
• error model
• oauth2 client
• event client (over mqtt)
• user endpoint
• logger
• utils

Prerequisites

• node.js lts version.
  • nvm is recommended to switch between node.js version with ease.
• Visual Studio Code (Optional, Recommended).
  • TSLint plugin for VSCode.
• Run the server with the auvious-devops

Getting Started

1. Clone auvious-api-common.

   git clone http://colab.teledrom.com/angel/auvious-api-common.git

2. Add the template project as a remote repo.

   git remote add template http://colab.teledrom.com/angel/auvious-api-template.git

3. Fetch the template remote repo's latest changes.

   git fetch template

4. Merge the template remote repo's master branch to the current repo master branch.

   ```sh
   git merge template/master
   ```

   Steps 3. & 4. can be used whenever it is needed to get the latest updates from the template project.

Quick tour

• src/v1 directory contains source code needed for any api module.

  • auth contains the OAuth2Client to be used for authorization.
  • event contains the EventClient to be used for realtime messaging. Is implemented over mqtt.
  • search contains the ApiSearchResource base class to be used for text searches.
  • user contains the ApiUserResource which is needed by any api module.

• test directory contains the unit tests of the api (jasmine & karma).

• demo directory contains a demo app that consumes the api.

• bin contains the js build generated from webpack

Terminology

Term	Description
Interface	Apart from its lang specific meaning, this term is used for pretty much anything that is public and will be called by a consumer.
Consumer	the callee of any interface exposed from the API
Client app	alias for consumer
{Something}Client	a public interface that exposes a certain feature. AuviousClient is the parent client which exposes EventClient for events & OAuth2Client for authorization.
ApiResource	A public interface that is used to access from or write to a web server. ApiResource is a common interface while ApiSearchResource extends the previous with full text search. ApiUserResource is the user specific search resource.
ApiResourceModel	Every model that is being returned by an ApiResource should extend this class. Checkout the User or the ApiSearchResult classes as examples usages.
EventFiringClient	a public interface that adds event handler support based on its generic argument. For example, the vent module's EventClient extends EventFiringClient
Postman	A public interface used to access an http service. Backed by axios but is used instead, for encapsulation purposes.

Build

# generates the library in the bin directory.
npm run build
# deletes bin directory.
npm run clean
# cleans & builds.
npm run clean-build

Test

• Run tests.
  This command will rebuild & include the api in the test project's node_modules, before running the unit tests.

  npm test

Demo

• An Angular app that uses the library can be found here

Dependencies

• When installing new dependencies via npm, make sure to remove any special characters in the version prefix. That way we prevent errors that might be introduced by their future updates.

• The dependencies should be updated manually and always be described with a fixed version (no ~ or ^ prefixes).

  # cool
  "typescript": "2.2.2",
  
  # not cool
  "typescript": "^2.2.2",

• Always register dependencies needed only at build time under the devDependencies key.

  # cool
  npm install --save-dev typescript
  
  # not cool
  npm install --save typescript

TODOs

• Add an Observable method in the ApiSearchResource.

Release notes

Version 1.3.0

• Added support for JWT token authentication in event server (mqtt)

Version 1.2.0

• Remove webpack build system
• Remove es6-promise lib
• Update Typescript to 2.9.2
• Rename src/v1 to lib
• instead of bin/bundle, dist/"compiled"

Version 1.1.2

• Fixed HTTP interceptor bug for catching only 401 response

Version 1.1.1

• Added response interceptor to refresh expired tokens
• Added handler to expose expirated token event
• Fixed wrong naming in 'IPagedCollection'

Version 1.1.0

• Changed mqtt event client from Paho-mqtt to mqttJS.

Version 1.0.0

• Stable version