service-activities2-node/README.md

Party activities tracking microservice in Node.js / ES2017 V2

# Party Activities Microservice for Node.js / ES2017 V2

This is a party activity logging microservice from the Pip.Services library.

* Logs important party activities (sign-ups, sign-ins, 
creation, changes or deletion of data items, ...)

The microservice currently supports the following deployment options:

* Deployment platforms: Standalone process, AWS Lambda function
* External APIs: HTTP/REST, gRPC
* Persistence: In-memory, flat files, MongoDB

This microservice has no dependencies on other microservices.

#### <a name="quick-links"></a> Quick Links

* [Contract](#contract)
* [Download](#download)
* [Develop](#develop):
    - [Environment Setup](#environment-setup)
    - [Installing](#installing)
    - [Building](#building)
    - [Testing](#testing)
    - [Contributing](#contributing)
* [Configure](#configure):
    - [Persistence](#persistence):
        * [Memory](#memory)
        * [File](#file)
        * [MongoDB](#mongodb)
    - [Service](#service)
    - [Controllers](#controllers):
        * [HTTP](#http)
        * [gRPC](#grpc)
* [Run](#run):
    - [Standalone Process](#standalone-process)
    - [AWS Lambda Function](#aws-lambda-function)
* [Use](#use)
* [Acknowledgements](#acknowledgements)
* [Source Documentation](docs/index.html)
* Client Libraries:
    - [Node.js Library](https://bitbucket.org/entinco/eic-services-users2/src/master/client-activities2-node)

## <a name="contract"></a> Contract

The logical contract of the microservice is presented below. For physical implementation (HTTP/REST, gRPC, Lambda), 
please refer to the documentation of the specific protocol.

```typescript
class PartyActivityV1 implements IStringIdentifiable {
    /* Identification */
    public id: string;
    public org_id?: string;

    /* Identification fields */
    public time: Date;
    public type: string;
    public party: ReferenceV1;

    /* References objects (notes, goals, etc.) */
    public ref_item?: ReferenceV1;
    public ref_parents?: ReferenceV1[];
    public ref_party?: ReferenceV1;

    /* Other details like % of progress or new status */
    public details?: StringValueMap;
}

class ReferenceV1 {
    public id: string;
    public type: string;
    public name?: string;
}

interface IActivitiesService {
    getPartyActivities(ctx: IContext, filter: FilterParams, paging: PagingParams): Promise<DataPage<PartyActivityV1>>;

    logPartyActivity(ctx: IContext, activity: PartyActivityV1): Promise<PartyActivityV1>;

    batchPartyActivities(ctx: IContext, activities: PartyActivityV1[]): Promise<void>;

    deletePartyActivities(ctx: IContext, filter: FilterParams): Promise<void>;
}
```

## <a name="download"></a> Download

The main way to get the microservice is to check it out directly from the Bitbucket repository:
```bash
git clone git@bitbucket.org:entinco/eic-services-users2.git
```

The microservice is also available as a NPM package under the same name. 
You can add a dependency to the microservice into the **package.json** file of your project:
```json
{
    ...
    "dependencies": {
        ...
        "service-activities2-node": "^1.0.*",
        ...
    }
}
```

## <a name="develop"></a> Develop

### <a name="environment-setup"></a> Environment Setup

This is a Node.js project and you have to install Node.js tools. 
You can download them from the official Node.js website: https://nodejs.org/en/download/

After Node.js is installed, you can verify its version:
```bash
node --version
```

Then you need to install some node tools (recommended to be global):
```bash
# Install typescript compiler
npm install typescript -g
 
# Install mocha test runner
npm install mocha -g
```

To work with the code repository, you need to install Git: https://git-scm.com/downloads

If you are planning to develop and test using persistent storages other than flat files, 
you may need to install database servers:
- Install MongoDB: https://www.mongodb.org/downloads

### <a name="installing"></a> Installing

After your environment is ready, you can copy the microservice source code from the repository:
```bash
git clone git@bitbucket.org:entinco/eic-services-users2.git
```

Then go to the project folder and install dependent modules:
```bash
# Install dependencies
npm install
```

If you have worked with the microservice before, you can check out the latest changes and update the dependencies:
```bash
# Update source code
git pull

# Update dependencies
npm update
```

### <a name="building"></a> Building

This microservice is written in TypeScript language which is transcompiled into JavaScript. 
So, if you make changes to the source code, you need to compile it before running or committing. 
The process will output compiled JavaScript files into the "obj" folder:
```bash
tsc
```

When you do continuous edit-build-test cycles, you can run the TypeScript compiler with "--watch" 
to detect and compile changes you make automatically:
```bash
tsc --watch
```

### <a name="testing"></a> Testing

Before you execute tests, you may need to set configuration options into a **config.yml** file, 
located by default in the "config" folder in the root of the project. 
For more information, see the [Configure](#configure) guide.

Run unit tests:
```bash
npm test
```

Execute benchmarks:
```bash
npm run benchmark
```

### <a name="contributing"></a> Contributing

Developers interested in contributing should read the following instructions:

- [How to Contribute](http://www.pipservices.org/contribute/)
- [Guidelines](http://www.pipservices.org/contribute/guidelines)
- [Styleguide](http://www.pipservices.org/contribute/styleguide)
- [Changelog](CHANGELOG.md)

> Please do **not** ask general questions in an issue. Issues are only to report bugs, request 
  enhancements, or request new features. For general questions and discussions, use the 
  [Contributors Forum](http://www.pipservices.org/forums/forum/contributors/).

It is important to note that for each release, the [Changelog](CHANGELOG.md) 
is a resource that will itemize all:

- Bug Fixes
- New Features
- Breaking Changes

## <a name="configure"></a> Configure
As a starting point, you can use this example to create your own **config.yml** file:
```yaml
---
- descriptor: "pip-services:context-info:default:default:1.0"
  name: "service-activities2"
  description: "Activities microservice for pip-services V2"

- descriptor: "pip-services:logger:console:default:1.0"
  level: "trace"

- descriptor: "activities:persistence:file:default:1.0"
  path: "../data/activities.json"

- descriptor: "activities:service:default:default:1.0"

- descriptor: "pip-services:endpoint:http:default:1.0"
  connection:
    protocol: "http"
    host: "0.0.0.0"
    port: 8080

- descriptor: "activities:controller:commandable-http:default:1.0"
```

Afterwards, check all configuration options. Specifically, pay attention to connection options 
for database and dependent microservices.

For more information on this section, read the 
[Pip.Services Configuration Guide](http://docs.pipservices.org/toolkit/recipes/config_file_syntax/).

### <a name="persistence"></a> Persistence

The microservice supports three types of persistence: in-memory, flat files, or MongoDB. 
In-memory and flat files are great for development and testing, 
while MongoDB is a good option with outstanding performance and scalability, suitable for demanding production installations. 
You can choose and configure the option that suits your needs.

#### <a name="memory"></a> Memory

Memory persistence has the following configuration properties:

* options: object - Misc configuration options
    - max_page_size: number - Maximum number of items per page (default: 100)

Example:
```yaml
- descriptor: "activities:persistence:memory:default:1.0"
  options:
    max_page_size: 100
```

#### <a name="file"></a> File

Flat file persistence has the following configuration properties:

* path: string - file path where SystemEventV1 objects are stored. The object are written into the file in JSON format.
* options: object - Misc configuration options
    - max_page_size: number - Maximum number of items per page (default: 100)

Example:
```yaml
- descriptor: "activities:persistence:file:default:1.0"
  path: "./data/activities.json"
```

#### <a name="mongodb"></a> MongoDB

MongoDB persistence has the following configuration properties:

* connection(s): object - MongoDB connection properties
* options: object - (optional) MongoDB connection options. See http://mongoosejs.com/docs/connections.html for more details.
* debug: boolean - (optional) Enables or disables connection debugging

Example:
```yaml
- descriptor: "accounts:persistence:file:default:1.0"
  connection:
    uri: "mongodb://localhost/pipservicestest"
  options:
    server:
      poolSize: 4
      socketOptions:
        keepAlive: 1
        connectTimeoutMS: 5000
    auto_reconnect: true
```

### <a name="service"></a> Service

Service has no configuration properties.

Example:
```yaml
- descriptor: "activities:service:default:default:1.0"
```

### <a name="controllers"></a> Controllers

The **controller** components (also called "endpoints") expose external microservice API for consumers. 
Each microservice can expose multiple APIs (HTTP/REST, gRPC) and multiple versions of the same API type.
At least one controller is required for the microservice to run successfully.

#### <a name="http"></a> HTTP

HTTP/REST controller has the following configuration properties:

* connection: object - HTTP transport configuration options
    - protocol: string - HTTP protocol - 'http' or 'https' (default is 'http')
    - host: string - IP address/hostname binding (default is '0.0.0.0')
    - port: number - HTTP port number
* swagger: object - (optional) Swagger controller integration options
    - enable: boolean - (optional) whether to enable Swagger integration
    - auto: boolean - (optional) whether to automatically configure Swagger integration

Example:
```yaml
# Common HTTP endpoint
- descriptor: "pip-services:endpoint:http:default:1.0"
  connection:
    protocol: "http"
    host: "0.0.0.0"
    port: "8080"

# HTTP controller
- descriptor: "activities:controller:commandable-http:default:1.0"
  swagger:
    enable: true
    auto: true
```

#### <a name="grpc"></a> gRPC

gRPC controller has the following configuration properties:

* connection: object - gRPC transport configuration options
    - protocol: string - gRPC protocol - 'http' or 'https' (default is 'http')
    - host: string - IP address/hostname binding (default is '0.0.0.0')
    - port: number - gRPC port number

Example:
```yaml
# Common GRPC endpoint
- descriptor: "pip-services:endpoint:grpc:default:1.0"
  connection:
    protocol: "http"
    host: "0.0.0.0"
    port: 8090

# GRPC controller
- descriptor: "activities:controller:grpc:default:1.0"

# Commandable GRPC controller
- descriptor: "activities:controller:commandable-grpc:default:1.0"
```

For more information on this section, read the 
[Pip.Services Configuration Guide](http://docs.pipservices.org/toolkit/recipes/config_file_syntax/).

## <a name="run"></a> Run

### <a name="standalone-process"></a> Standalone Process

The simplest way to deploy the microservice is to run it as a standalone process. 
This microservice is implemented in JavaScript and requires installation of Node.js. 
You can get it from the official site at https://nodejs.org/en/download

**Step 1.** Download the microservice by following the [Download](#download) instructions.

**Step 2.** Add a **config.yml** file to the "config" folder in the root of the project and set configuration parameters. 
See the [Configure](#configure) guide for details.

**Step 3.** Start the microservice:
```bash
node ./bin/main.js
```

### <a name="aws-lambda-function"></a> AWS Lambda Function

This microservice can also be packaged and deployed to AWS as a Lambda function. 
This microservice is implemented in JavaScript and requires the installation of Node.js. 
You can download it from the official Node.js website: https://nodejs.org/en/download/

**Step 1.** Download the microservice by following the [Download](#download) instructions.

**Step 2.** Add a **config.yml** file to the "config" folder in the root of the project and set configuration parameters. 
See the [Configure](#configure) guide for details.

**Step 3.** Go to the project folder and install the dependent modules:
```bash
npm install
```

**Step 4.** Package the project folder into a .zip file:
```bash
zip -r lambda_function.zip .
```

**Step 5.** Go to the AWS Lambda console and create a new Lambda function.

- **Name:** "service-activities2-node"
- **Runtime:** Choose "Node.js 14.x" or newer
- **Function code:** Upload the .zip package of the project folder

**Step 6:** Configure any triggers necessary to invoke the function or invoke it via the AWS Lambda console.

## <a name="use"></a> Use

The easiest way to work with the microservice is to use the client library. 
The complete list of available client libraries for different languages is listed in the [Quick Links](#quick-links).

If you use Node.js, then you can add a dependency to the client library into the **package.json** file of your project:
```json
{
    ...
    "dependencies": {
        ...
        "client-activities2-node": "^1.0.*",
        ...
    }
}
```

Then install the dependency:
```bash
# Install new dependencies
npm install

# Update already installed dependencies
npm update
```

Inside your code, get the reference to the client library:
```javascript
let node_lib = new require('client-activities2-node');
```

Define client configuration parameters that match the configuration of the microservice external API:
```javascript
// Client configuration
let config = {
    connection: {
        protocol: 'http',
        host: 'localhost', 
        port: 8080
    }
};
```

Instantiate the client and open a connection to the microservice:
```javascript
// Create the client instance
let client = node_lib.ActivitiesHttpClientV1(config);

// Connect to the microservice
try {
    await client.open(null);
    // Work with the microservice
    ...
}
catch (err) {
    console.error('Connection to the microservice failed');
    console.error(err);
}
```

Now the client is ready to perform operations:
```javascript
// Log party activity
let activity = await client.logPartyActivity(
    null,
    { 
        type: 'signup',
        party: {
            id: '123',
            name: 'Test User'
        }
    }
);
```

```javascript
let now = new Date();
// Get the list of system activities
let page = await client.getPartyActivities(
    null,
    {
        party_id: '123',
        from_time: new Date(now.getTime() - 24 * 3600 * 1000),
        to_time: now
    },
    {
        total: true,
        skip: 0,
        take: 10
    }
);
```

## <a name="acknowledgements"></a> Acknowledgements

This microservice was created by [Sergey Seroukhov](mailto:seroukhov@entinco.com) 
and is currently maintained by [Michael Seroukhov](mailto:mseroukhov@entinco.com).