# @indigoframework/agent

> NodeJS module that exposes functions to create Stratumn agents using Javascript

Latest version **0.3.0-rc1** (published 2018-03-29) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @indigoframework/agent
pnpm add @indigoframework/agent
yarn add @indigoframework/agent
bun add @indigoframework/agent
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.3.0-rc1 |
| Published | 2018-03-29 |
| First published | 2017-12-20 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 13 |
| Unpacked size | 326.5 KB |
| Known vulnerabilities | 0 (+6 in 4 direct dependencies) |
| Install scripts | no |
| Author | Stratumn Team |
| Maintainers | adrien-stratumn, alexppxela, bejito, conord33, jeremie-stratumn, piedup, sf-stratumn, simonvadee, t-bast |
| Keywords | stratumn, sdk, blockchain, client |

## Links

- npm: https://www.npmjs.com/package/@indigoframework/agent
- Repository: https://github.com/stratumn/js-indigocore
- Homepage: https://github.com/stratumn/js-indigocore#readme
- Issues: https://github.com/stratumn/js-indigocore/issues
- npm.io page: https://npm.io/package/@indigoframework/agent

## Dependencies (13)

- [co](https://npm.io/package/co.md) ^4.6.0
- [qs](https://npm.io/package/qs.md) ^6.5.1
- [ws](https://npm.io/package/ws.md) ^2.0.0
- [cors](https://npm.io/package/cors.md) ^2.7.1
- [uuid](https://npm.io/package/uuid.md) ^3.0.0
- [express](https://npm.io/package/express.md) ^4.14.0
- [request](https://npm.io/package/request.md) ^2.73.0
- [superagent](https://npm.io/package/superagent.md) ^2.1.0
- [body-parser](https://npm.io/package/body-parser.md) ^1.15.2
- [babel-runtime](https://npm.io/package/babel-runtime.md) ^6.26.0
- [canonicaljson](https://npm.io/package/canonicaljson.md) ^1.0.1
- [async-middleware](https://npm.io/package/async-middleware.md) ^1.2.1
- [@indigoframework/utils](https://npm.io/package/@indigoframework/utils.md) ^0.3.0-rc1

## Alternatives

- [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads
- [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads
- [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads
- [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads
- [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads

## Recent versions

- 0.3.0-rc1 (latest) — 2018-03-29
- 0.3.0-alpha1 — 2018-03-15
- 0.2.0 — 2018-01-02
- 0.2.0-3 — 2017-12-21
- 0.2.0-2 — 2017-12-21
- 0.2.0-1 — 2017-12-20
- 0.2.0-0 — 2017-12-20

## README

# Indigo agent for NodeJS

This NodeJS module exposes functions to create Indigo agents using Javascript.

[![npm](https://img.shields.io/npm/v/@indigoframework/agent.svg)](https://www.npmjs.com/package/@indigoframework/agent)

Copyright 2017 Stratumn SAS. All rights reserved.

Unless otherwise noted, the Stratumn Agent Javascript Library source files are distributed under the Apache License 2.0 found in the LICENSE file.

## Creating an HTTP server for an agent

```javascript
var express = require('express');
var Agent = require('@indigoframework/agent');
var plugins = Agent.plugins;

// Load actions.
// Assumes your actions are in ./lib/actions.
var actions = require('./lib/actions');

// Creates an HTTP store client to save segments.
// Assumes an HTTP store server is available on env.STRATUMN_STORE_URL or http://store:5000.
var storeHttpClient = Agent.storeHttpClient(process.env.STRATUMN_STORE_URL || 'http://store:5000');

// Creates an HTTP fossilizer client to fossilize segments.
// Assumes an HTTP fossilizer server is available on env.STRATUMN_FOSSILIZER_URL or http://fossilizer:6000.
var fossilizerHttpClient = Agent.fossilizerHttpClient(process.env.STRATUMN_FOSSILIZER_URL || 'http://fossilizer:6000');

// Creates an agent
var agent = Agent.create({
    agentUrl: 'http://localhost:3000',               // the agent needs to know its root URL,·
});

// Adds a process from a name, its actions, the store client, and the fossilizer client.
// As many processes as one needs can be added. A different storeHttpClient and fossilizerHttpClient may be used.
agent.addProcess("my_first_process", actions, storeHttpClient, fossilizerHttpClient, {
  plugins: [plugins.localTime]                     // pick any plugins from src/plugins or develop your own - order matters
});

// Creates an HTTP server for the agent with CORS enabled.
var agentHttpServer = Agent.httpServer(agent, { cors: {} });

// Create the Express server.
const app = express();
app.disable('x-powered-by');

// Mount agent on the root path of the server.
app.use('/', agentHttpServer);

// Create server by binding app and websocket connection
const server = Agent.websocketServer(app, storeHttpClient);

// Start the server
server.listen(3000, () => {
  console.log('Listening on ' + server.address().port);
});

// You can also add processes on-the-fly after the server has started listening
agent.addProcess("my_second_process", actions, storeHttpClient, fossilizerHttpClient, {
  plugins: [plugins.localTime]
});
```

The documentation for the HTTP API is available in [doc/swaggerDoc.md](doc/swaggerDoc.md). It uses [OpenAPI ver. 2](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) (fka Swagger). You can also use [doc/swagger.json](doc/swagger.json) with [Swagger UI](https://swagger.io/swagger-ui/) for instance:

```
docker run -p 8080:8080 -e SWAGGER_JSON=/opt/swagger.json -v $(pwd)/doc:/opt swaggerapi/swagger-ui
```

## Advanced usage

- `create` creates an agent instance.
- `storeHttpClient` creates an instance to work with stores via HTTP.
- `fossilizerHttpClient` creates an instance to work with fossilizers via HTTP.
- `httpServer` creates an app for the agent
- `websocketServer`bind websocket connection to app and returns server

## Plugins

An agent plugin enriches the content of a segment. It may implement four methods:

- `willCreate(link)`
is called right before a transition function from the agent's actions. It takes the existing link as an argument. It should be updated in-place.

- `didCreateLink(link)`
is called whenever a link has been created by a transition function. It takes the new link as an argument. It should be updated in-place.

- `filterSegment(segment)`
is called when segments are retrieved by the agent from the underlying storage. It should return `true` if the plugins accepts the segment, `false` otherwise.
Filters are applied sequentially in the reverse order they are defined.

All methods are optional. They can either be synchronous or return a Promise.

### Available plugins:

- `agentUrl`: Saves in segment meta the URL that can be used to retrieve a segment.
- `encryptedState`: Encrypts the state before the segment is saved. Filters out segment that cannot be decrypted.
- `localTime`: Saves the local timestamp in the link meta information.
- `signedState`: Signs the state before the segment is saved. Filters out segments whose signature is invalid.
- `stateHash`: Computes and adds the hash of the state in meta.

## Development

To regenerate the HTTP API documentation, run:

```
$ npm run swagger:generate
```

---
_Source: https://npm.io/package/@indigoframework/agent · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._