# grid3_client

> [![npm version](https://img.shields.io/npm/v/grid3_client.svg)](https://badge.fury.io/js/grid3_client) [![Build](https://github.com/threefoldtech/grid3_client_ts/actions/workflows/build.yml/badge.svg)](https://github.com/threefoldtech/grid3_client_ts/acti

Latest version **2.1.0-rc2** (published 2023-04-05) · ISC license · 0 weekly downloads

## Install

```sh
npm install grid3_client
pnpm add grid3_client
yarn add grid3_client
bun add grid3_client
```

Provides the commands `httpserver`, `twinserver`.

## Health

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

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.1.0-rc2 |
| Published | 2023-04-05 |
| First published | 2021-10-10 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 29 |
| Unpacked size | 1.3 MB |
| Known vulnerabilities | 0 (+24 in 2 direct dependencies) |
| Install scripts | no |
| Author | Ahmed Hanafy |
| Maintainers | hanafy725 |

## Links

- npm: https://www.npmjs.com/package/grid3_client
- Repository: https://github.com/threefoldtech/grid3_client_ts
- Homepage: https://github.com/threefoldtech/grid3_client_ts/blob/development/README.md
- npm.io page: https://npm.io/package/grid3_client

## Dependencies (29)

- [axios](https://npm.io/package/axios.md) ^0.27.2
- [bip39](https://npm.io/package/bip39.md) ^3.0.4
- [uuid4](https://npm.io/package/uuid4.md) ^2.0.2
- [buffer](https://npm.io/package/buffer.md) ^6.0.3
- [algosdk](https://npm.io/package/algosdk.md) ^1.19.0
- [express](https://npm.io/package/express.md) ^4.18.1
- [netaddr](https://npm.io/package/netaddr.md) ^1.1.0
- [url-join](https://npm.io/package/url-join.md) ^4.0.1
- [crypto-js](https://npm.io/package/crypto-js.md) ^4.1.1
- [tweetnacl](https://npm.io/package/tweetnacl.md) ^1.0.3
- [url-parse](https://npm.io/package/url-parse.md) ^1.5.10
- [await-lock](https://npm.io/package/await-lock.md) ^2.1.0
- [decimal.js](https://npm.io/package/decimal.js.md) ^10.3.1
- [private-ip](https://npm.io/package/private-ip.md) ^2.3.3
- [rmb-sdk-ts](https://npm.io/package/rmb-sdk-ts.md) 1.1.3
- [typescript](https://npm.io/package/typescript.md) ^4.7.4
- [http-server](https://npm.io/package/http-server.md) ^14.1.1
- [stellar-sdk](https://npm.io/package/stellar-sdk.md) ^10.4.1
- [@jimber/pkid](https://npm.io/package/@jimber/pkid.md) 1.0.4
- [appdata-path](https://npm.io/package/appdata-path.md) ^1.0.0
- [tweetnacl-util](https://npm.io/package/tweetnacl-util.md) ^0.15.1
- [class-validator](https://npm.io/package/class-validator.md) ^0.14.0
- [@noble/secp256k1](https://npm.io/package/@noble/secp256k1.md) ^1.7.1
- [reflect-metadata](https://npm.io/package/reflect-metadata.md) ^0.1.13
- [class-transformer](https://npm.io/package/class-transformer.md) ^0.5.1
- [tfgrid-api-client](https://npm.io/package/tfgrid-api-client.md) 1.27.0
- [libsodium-wrappers](https://npm.io/package/libsodium-wrappers.md) ^0.7.10
- [exponential-backoff](https://npm.io/package/exponential-backoff.md) ^3.1.0
- [ts-rmb-redis-client](https://npm.io/package/ts-rmb-redis-client.md) 1.0.0

## Recent versions

- 2.1.0-rc2 (latest) — 2023-04-05
- 2.1.0-rc1 — 2023-04-03
- 2.0.0 — 2023-03-28
- 2.0.0-rc12 — 2023-03-21
- 2.0.0-rc11 — 2023-03-21
- 2.0.0-rc10 — 2023-03-09
- 2.0.0-rc9 — 2023-03-09
- 2.0.0-rc8 — 2023-03-08
- 2.0.0-rc7 — 2023-03-07
- 2.0.0-rc6 — 2023-03-06
- 2.0.0-rc5 — 2023-03-05
- 1.5.3 — 2023-03-05
- 1.5.2 — 2023-03-05
- 2.0.0-rc4 — 2023-03-03
- 1.5.1 — 2023-03-02
- … 97 more at https://npm.io/package/grid3_client/versions

## README

# grid3_client_ts

[![npm version](https://img.shields.io/npm/v/grid3_client.svg)](https://badge.fury.io/js/grid3_client)
[![Build](https://github.com/threefoldtech/grid3_client_ts/actions/workflows/build.yml/badge.svg)](https://github.com/threefoldtech/grid3_client_ts/actions/workflows/build.yml)
[![tests](https://github.com/threefoldtech/grid3_client_ts/actions/workflows/tests.yml/badge.svg)](https://github.com/threefoldtech/grid3_client_ts/actions/workflows/tests.yml)
[![code coverage](https://codecov.io/gh/threefoldtech/grid3_client_ts/branch/development/graph/badge.svg)](https://codecov.io/gh/threefoldtech/grid3_client_ts/branch/development)

Github repo: [grid3_client_ts](https://github.com/threefoldtech/grid3_client_ts.git)

grid3_client is a client used for deploying workloads (VMs, ZDBs, k8s, etc.) on grid3.

## Prerequisites

- node 16.13.1 or higher
- npm 8.2.0 or higher
- may need to install libtool `apt-get install libtool`

## Installation

> **Warning**: For **Qanet**, Please use @2.0.0 version

> **Warning**: For **Testnet**, Please use @2.0.0 version

> **Warning**: For **Mainnet**, Please use @1.5.0 version

### External package

```bash
npm install grid3_client
```

or

```bash
yarn add grid3_client
```

### Local usage

- Clone the repository

```bash
git clone https://github.com/threefoldtech/grid3_client_ts.git
```

- Install it

```bash
npm install
```

or

```bash
yarn install
```

## Getting started

### Client configuration

- Network environment: should select dev environment, qa, test or main.

- Mnemonic: 12 words for your account. [create one](https://library.threefold.me/info/manual/#/getstarted/manual__dashboard_portal_polkadot_create_account)

- Store secret: it's any word that will be used for encrypting/decrypting the keys on threefold key-value store.

- project name: it's a name to isolate the deployments into a namespace.

    **Note:** only network can't be isolated, all project can see the same network.

### Create client instance

- Here's a simple example of creating a client instance with the default configurations.

- or you can check more advanced configuration [here](./docs/client_configuration.md).

    ```ts
    async function getClient(): Promise<GridClient> {
    const gridClient = new GridClient({
        network: config.network,
        mnemonic: config.mnemonic,
    });
    await gridClient.connect();

    return gridClient;
    }
    ```

- You can set your configurations through environment variables or [JSON config file](./scripts/config.json) as seen [here](./scripts/client_loader.ts).

- With clientOptions being added, all urls are now configured. So, you can easily get the proxy URL for the used network simply by:

    ```ts
    const proxyURL = gridClient.clientOptions.proxyURL
    ```

for more details, check [client options](./src/client.ts)

**Important Note**: grid client should be disconnected after finishing its usage.

```ts
gridClient.disconnect();
```

### Using the client

> This section assumes that you are using the client configuration from [client_loader.ts](./scripts/client_loader.ts)

- After creating a client instance you can call it in any of your scripts using `getClient()`.

    ```ts
    const grid3 = getClient();
    ```

- And then you can use this client instance with any of the client [modules](./docs/module.md).

- For example to deploy a VM you will need to use the machines module with the client and it can be used as follows. you can find the full example script [here](./scripts/single_vm.ts).

  - To deploy a VM

    ```ts
    await grid3.machines.deploy(vms);
    ```

  - To delete a VM

    ```ts
    await grid3.machines.delete({ name: vms.name });
    ```

- More example scripts can be found [here](./scripts)

### Running the scripts

- Before Running the scripts make sure you have a `tsconfig.json` file. here is an example file.

    ```json
    {
        "compilerOptions": {
            "noImplicitAny": false,
            "module": "commonjs",
            "target": "esnext",
            "lib": [
                "ESNext",
                "DOM"
            ],
            "types": [
                "node",
                "jest"
            ],
            "declaration": true,
            "declarationMap": true,
            "outDir": "./dist/node",
            "esModuleInterop": true,
            "emitDecoratorMetadata": true,
            "experimentalDecorators": true,
            "allowJs": true,
            "baseUrl": "."
        },
        "include": [
            "src/**/*"
        ]
    }
    ```

- After following the previous examples to create a client instance and using it in a script, you can then execute this script using [ts-node](https://www.npmjs.com/ts-node).

    ```bash
    npx ts-node --project tsconfig-node.json filename.ts
    ```

    or

    ```bash
    yarn run ts-node --project tsconfig-node.json filename.ts
    ```

## Usage examples

- [Scripts](./scripts/README.md)
- [HTTP Server](./docs/http_server.md)
- [RMB Server](./docs/rmb_server.md)

## API Docs

<https://threefoldtech.github.io/grid3_client_ts/api/>

## Testing

- [Test setup](./docs/test_setup.md)
- [How to run tests](./docs/tests.md)

## Related Documentations

- [Configure the editor/IDE](./docs/editor_config.md)
- [Contribution Guide](./docs/contribution.md)
- [Grid Client documentation](https://library.threefold.me/info/manual/#/manual__grid3_javascript_home)

- [Pipelines documentation](./docs/workflows.md)
- [Release process](./docs/release.md)

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