# universa-toolkit

> Javascript library required to perform basic operations with Universa networks

Latest version **0.1.0** (published 2019-12-09) · (BSD-3-Clause OR GPL-2.0) license · 0 weekly downloads

## Install

```sh
npm install universa-toolkit
pnpm add universa-toolkit
yarn add universa-toolkit
bun add universa-toolkit
```

## 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.1.0 |
| Published | 2019-12-09 |
| First published | 2019-12-09 |
| Weekly downloads | 0 |
| License | (BSD-3-Clause OR GPL-2.0) |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 998.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Universa Blockchain Team |
| Maintainers | anzhu |
| Keywords | network, frontend, client |

## Links

- npm: https://www.npmjs.com/package/universa-toolkit
- Repository: https://github.com/UniversaBlockchain/toolkit-js
- Homepage: https://github.com/UniversaBlockchain/toolkit-js#readme
- Issues: https://github.com/UniversaBlockchain/toolkit-js/issues
- npm.io page: https://npm.io/package/universa-toolkit

## Dependencies (2)

- [xhr-request](https://npm.io/package/xhr-request.md) ^1.1.0
- [universa-minicrypto](https://npm.io/package/universa-minicrypto.md) ^0.3.0

## 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.1.0 (latest) — 2019-12-09

## README

## universa-toolkit

Minimalistic Javascript library required to perform basic operations with Universa Network, based on universa-minicrypto.

## Installation

### Node.js

For usage in an existing Node.js project, add it to your dependencies:

```
$ npm install universa-toolkit
```

or with yarn:

```
$ yarn add universa-toolkit
```


And use it with the following line wherever you need it:

```javascript
const Universa = require('universa-toolkit');
```

### Web

In root folder of package run

```bash
npm install
npm run build
```

In folder `dist` there will be `toolkit.js`.

Simply copy `dist/toolkit.js` to wherever you keep your vendor scripts and include
it as a script:

```html
<script src="path/to/toolkit.js"></script>
```

## Usage

### Connecting to network

Connect to network with default topology

```js
const { Network } = Universa;
const { PrivateKey } = Universa.pki;

// privateKey is PrivateKey instance
const network = new Network(privateKey);
let response;

try { await network.connect(); }
catch (err) { console.log("network connection error: ", err); }

try { response = await network.command("sping"); }
catch (err) { console.log("on network command:", err); }
```

Connect to network with topology, provided by file path

```js
const { Network } = Universa;
const { PrivateKey } = Universa.pki;

// privateKey is PrivateKey instance
const network = new Network(privateKey, {
  topologyFile: "/path/to/mainnet.json"
});
let response;

try { await network.connect(); }
catch (err) { console.log("network connection error: ", err); }

try { response = await network.command("sping"); }
catch (err) { console.log("on network command:", err); }
```

Connect to network with provided topology

```js
const { Network, Topology } = Universa;
const { PrivateKey } = Universa.pki;

const topology = Topology.load(require("/path/to/mainnet.json"));

// privateKey is PrivateKey instance
const network = new Network(privateKey, { topology });
let response;

try { await network.connect(); }
catch (err) { console.log("network connection error: ", err); }

try { response = await network.command("sping"); }
catch (err) { console.log("on network command:", err); }
```

(Browser only) Connect to network and save topology to localStorage

```js
const { Network } = Universa;
const { PrivateKey } = Universa.pki;

// privateKey is PrivateKey instance
const network = new Network(privateKey, {
  topologyKey: "local_storage_key_to_store"
});
let response;

try { await network.connect(); }
catch (err) { console.log("network connection error: ", err); }

try { response = await network.command("sping"); }
catch (err) { console.log("on network command:", err); }
```

### Topology

Load topology from file
```js
const { Topology } = Universa;

const topology = Topology.load(require("/path/to/mainnet.json"));
```

Get topology from network instance
```js
const { Network } = Universa;
const { PrivateKey } = Universa.pki;

// privateKey is PrivateKey instance
const network = new Network(privateKey);
await network.connect();

const { topology } = network; // Updated topology instance
```

Update topology
```js
const { Topology } = Universa;

const topology = Topology.load(require("/path/to/mainnet.json"));
const done = await topology.update(); // updates topology that then can be saved
```

Pack topology to save as file
```js
const fs = require('fs');
const { Network } = Universa;
const { PrivateKey } = Universa.pki;

// privateKey is PrivateKey instance
const network = new Network(privateKey);
const { topology } = network; // Topology instance

const packedTopology = topology.pack();
const json = JSON.stringify(packedTopology);
fs.writeFile('mainnet.json', json);
```

### Running commands

network.command(commandName, parameters) - returns Promise with result

```js
const { Network } = Universa;
const { PrivateKey } = Universa.pki;

// privateKey is PrivateKey instance
const network = new Network(privateKey);
let response;

try { await network.connect(); }
catch (err) { console.log("network connection error: ", err); }

try {
  // approvedId is Uint8Array
  response = await network.command("getState", {
    itemId: { __type: "HashId", composite3: approvedId }
  });
}
catch (err) { console.log("on network command:", err); }
```

### Check full contract status

Special command to check contract status over network
isApproved(contractId, trustLevel: Double) // Promise[Boolean]

```js
const { Network } = Universa;
const { PrivateKey } = Universa.pki;

// privateKey is PrivateKey instance
const network = new Network(privateKey);
let isApproved; // boolean

try { await network.connect(); }
catch (err) { console.log("network connection error: ", err); }

try {
  // approvedId can be Uint8Array or base64 string
  isApproved = await network.isApproved(approvedId, 0.6);
}
catch (err) { console.log("on network command:", err); }
```

## Running tests

Run tests
```bash
npm test
```

Run coverage
```bash
npm run coverage
```

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