provide-js

a Javascript library to help you use Provide's NChain, Ident, and InterPlanetaryFileSystem APIs

License

MIT © 2020 Provide Technologies Inc.

Table of contents

1. Install
2. WebPack
3. NChain
   1. NChain with JavaScript and Promise
   2. NChain with JavaScript and RxJS
   3. NChain with TypeScript and Promise
   4. NChain with TypeScript and RxJS
4. Ident
   1. Ident with JavaScript and Promise
   2. Ident with JavaScript and RxJS
   3. Ident with TypeScript and Promise
   4. Ident with TypeScript and RxJS
5. IpfsClient
   1. IpfsClient with JavaScript and Promise
   2. IpfsClient with JavaScript and RxJS
   3. IpfsClient with TypeScript and Promise
   4. IpfsClient with TypeScript and RxJS

Install

> yarn add provide-js

or

> npm install provide-js --save

Recommended for uploading files to IPFS:

> yarn add pull-file-reader

or

> npm install pull-file-reader --save

WebPack

If using webpack, add node options to your webpack config.

module.exports = {
  node: {
    buffer: true,
    crypto: true,
    os: true,
    path: true,
    stream: true,
  }
};

NChain

Here are usage examples for 2 of the 50+ NChain methods. The others have similar usage.

NChain with JavaScript and Promise

Fetch connectors

import { NChain } from 'provide-js';

const token = 'myapitoken';
const dappId = 'mydappid';
const networkId = 'mynetworkid';
const NChain = new NChain(token);
const params = {
  application_id: dappId,
  network_id: networkId,
};

NChain.fetchConnectors(params).then(
  (response) => {
    console.log(response.requestBody);
    console.log(response.requestHeaders);
    console.log(response.responseBody);
    console.log(response.responseHeaders);
    console.log(response.xhr);
    const connectorList = JSON.parse(response.responseBody);
    console.log(connectorList);
  }
).catch(
  (response) => {
    console.log('Error!');
    console.log(response.xhr);
  }
);

Execute a contract

import { NChain } from 'provide-js';

const token = 'myapitoken';
const methodParams = ["1stparamvalue","2ndparamvalue"];
const executionParams = {
    method: 'methodname',
    params: methodParams,
    value: 0,
    wallet_id: 'mywalletid',
};
const contractId = 'mycontractid';
const NChain = new NChain(token);

NChain.executeContract(contractId, executionParams).then(
  (response) => {
    console.log(response.requestBody);
    console.log(response.requestHeaders);
    console.log(response.responseBody);
    console.log(response.responseHeaders);
    console.log(response.xhr);
  }
).catch(
  (response) => {
    console.log('Error!');
    console.log(response.xhr);
  }
);

NChain with JavaScript and RxJS

Fetch connectors

import { NChain } from 'provide-js';
import { from } from 'rxjs';
import { first } from 'rxjs/operators';

const token = 'myapitoken';
const dappId = 'mydappid';
const networkId = 'mynetworkid';
const NChain = new NChain(token);
const params = {
  application_id: dappId,
  network_id: networkId,
};
const observable = from(NChain.fetchConnectors(params));

observable.pipe(first()).subscribe(
  (response) => {
    console.log(response.requestBody);
    console.log(response.requestHeaders);
    console.log(response.responseBody);
    console.log(response.responseHeaders);
    console.log(response.xhr);
    const connectorList = JSON.parse(response.responseBody);
    console.log(connectorList);
  },
  (response) => {
    console.log('Error!');
    console.log(response.xhr);
  }
);

Execute a contract

import { NChain } from 'provide-js';
import { from } from 'rxjs';
import { first } from 'rxjs/operators';

const token = 'myapitoken';
const methodParams = ["1stparamvalue","2ndparamvalue"];
const executionParams = {
    method: 'methodname',
    params: methodParams,
    value: 0,
    wallet_id: 'mywalletid',
};
const contractId = 'mycontractid';
const NChain = new NChain(token);
const observable = from(NChain.executeContract(contractId, executionParams));

observable.pipe(first()).subscribe(
  (response) => {
    console.log(response.requestBody);
    console.log(response.requestHeaders);
    console.log(response.responseBody);
    console.log(response.responseHeaders);
    console.log(response.xhr);
  },
  (response) => {
    console.log('Error!');
    console.log(response.xhr);
  }
);

NChain with TypeScript and Promise

Fetch connectors

import { ApiClientResponse, NChain } from 'provide-js';

const token: string = 'myapitoken';
const dappId: string = 'mydappid';
const networkId: string = 'mynetworkid';
const NChain = new NChain(token);
const params = {
  application_id: dappId,
  network_id: networkId,
};

NChain.fetchConnectors(params).then(
  (response: ApiClientResponse) => {
    console.log(response.requestBody);
    console.log(response.requestHeaders);
    console.log(response.responseBody);
    console.log(response.responseHeaders);
    console.log(response.xhr);
    const connectorList = JSON.parse(response.responseBody);
    console.log(connectorList);
  }
).catch(
  (response: ApiClientResponse) => {
    console.log('Error!');
    console.log(response.xhr);
  }
);

Execute a contract

import { ApiClientResponse, NChain } from 'provide-js';

const token: string = 'myapitoken';
const methodParams: (number|string)[] = ["1stparamvalue","2ndparamvalue"];
const executionParams: object = {
    method: 'methodname',
    params: methodParams,
    value: 0,
    wallet_id: 'mywalletid',
};
const contractId: string = 'mycontractid';
const NChain: NChain = new NChain(token);

NChain.executeContract(contractId, executionParams).then(
  (response: ApiClientResponse) => {
    console.log(response.requestBody);
    console.log(response.requestHeaders);
    console.log(response.responseBody);
    console.log(response.responseHeaders);
    console.log(response.xhr);
  }
).catch(
  (response: ApiClientResponse) => {
    console.log('Error!');
    console.log(response.xhr);
  }
);

NChain with TypeScript and RxJS

Fetch connectors

import { ApiClientResponse, NChain } from 'provide-js';
import { from, Observable } from 'rxjs';
import { first } from 'rxjs/operators';

const token: string = 'myapitoken';
const dappId: string = 'mydappid';
const networkId: string = 'mynetworkid';
const NChain = new NChain(token);
const params = {
  application_id: dappId,
  network_id: networkId,
};
const observable: Observable<ApiClientResponse> = from(NChain.fetchConnectors(params));

observable.pipe(first()).subscribe(
  (response: ApiClientResponse) => {
    console.log(response.requestBody);
    console.log(response.requestHeaders);
    console.log(response.responseBody);
    console.log(response.responseHeaders);
    console.log(response.xhr);
    const connectorList = JSON.parse(response.responseBody);
    console.log(connectorList);
  },
  (response: ApiClientResponse) => {
    console.log('Error!');
    console.log(response.xhr);
  }
);

Execute a contract

import { ApiClientResponse, NChain } from 'provide-js';
import { from, Observable } from 'rxjs';
import { first } from 'rxjs/operators';

const token: string = 'myapitoken';
const methodParams: (number|string)[] = ["1stparamvalue","2ndparamvalue"];
const executionParams = {
    method: 'methodname',
    params: methodParams,
    value: 0,
    wallet_id: 'mywalletid',
};
const contractId: string = 'mycontractid';
const NChain: NChain = new NChain(token);
const observable: Observable<ApiClientResponse> = from<ApiClientResponse>(NChain.executeContract(contractId, executionParams));

observable.pipe(first()).subscribe(
  (response: ApiClientResponse) => {
    console.log(response.requestBody);
    console.log(response.requestHeaders);
    console.log(response.responseBody);
    console.log(response.responseHeaders);
    console.log(response.xhr);
  },
  (response: ApiClientResponse) => {
    console.log('Error!');
    console.log(response.xhr);
  }
);

Ident

Here is a usage example for 1 of the 10+ Ident methods. The others have similar usage.

Ident with JavaScript and Promise

Fetch DApp details

import { Ident } from 'provide-js';

const token = 'myapitoken';
const dappId = 'mydappid';
const ident = new Ident(token);

ident.fetchApplicationDetails(dappId).then(
  (response) => {
    console.log(response.requestBody);
    console.log(response.requestHeaders);
    console.log(response.responseBody);
    console.log(response.responseHeaders);
    console.log(response.xhr);
    const dappDetails = JSON.parse(response.responseBody);
    console.log(dappDetails);
  }
).catch(
  (response) => {
    console.log('Error!');
    console.log(response.xhr);
  }
);

Ident with JavaScript and RxJS

Fetch DApp details

import { Ident } from 'provide-js';
import { from } from 'rxjs';
import { first } from 'rxjs/operators';

const token = 'myapitoken';
const dappId = 'mydappid';
const ident = new Ident(token);
const observable = from(ident.fetchApplicationDetails(dappId));

observable.pipe(first()).subscribe(
  (response) => {
    console.log(response.requestBody);
    console.log(response.requestHeaders);
    console.log(response.responseBody);
    console.log(response.responseHeaders);
    console.log(response.xhr);
    const dappDetails = JSON.parse(response.responseBody);
    console.log(dappDetails);
  },
  (response) => {
    console.log('Error!');
    console.log(response.xhr);
  }
);

Ident with TypeScript and Promise

Fetch DApp details

import { ApiClientResponse, Ident } from 'provide-js';

const token: string = 'myapitoken';
const dappId: string = 'mydappid';
const ident = new Ident(token);

ident.fetchApplicationDetails(dappId).then(
  (response: ApiClientResponse) => {
    console.log(response.requestBody);
    console.log(response.requestHeaders);
    console.log(response.responseBody);
    console.log(response.responseHeaders);
    console.log(response.xhr);
    const dappDetails = JSON.parse(response.responseBody);
    console.log(dappDetails);
  }
).catch(
  (response: ApiClientResponse) => {
    console.log('Error!');
    console.log(response.xhr);
  }
);

Ident with TypeScript and RxJS

Fetch DApp details

import { ApiClientResponse, Ident } from 'provide-js';
import { from, Observable } from 'rxjs';
import { first } from 'rxjs/operators';

const token: string = 'myapitoken';
const dappId: string = 'mydappid';
const ident = new Ident(token);
const observable: Observable<ApiClientResponse> = from(ident.fetchApplicationDetails(dappId));

observable.pipe(first()).subscribe(
  (response: ApiClientResponse) => {
    console.log(response.requestBody);
    console.log(response.requestHeaders);
    console.log(response.responseBody);
    console.log(response.responseHeaders);
    console.log(response.xhr);
    const dappDetails = JSON.parse(response.responseBody);
    console.log(dappDetails);
  },
  (response: ApiClientResponse) => {
    console.log('Error!');
    console.log(response.xhr);
  }
);

IpfsClient

Before you use the IpfsClient, you must have an IPFS node. If you don't have your own then you can use Provide's by not passing any constructor arguments.

You will need to have CORS set up. If you don't know much about CORS and just want to get playing quickly, run these 2 ipfs commands to allow all websites access to your IPFS node.

> ipfs config --json API.HTTPHeaders.Access-Control-Allow-Origin "[\"*\"]"
> ipfs config --json API.HTTPHeaders.Access-Control-Allow-Credentials "[\"true\"]"

IpfsClient with JavaScript and Promise

Create a text file

import { Buffer } from 'buffer';
import { IpfsClient } from 'provide-js';

const ipfs = new IpfsClient('http', 'localhost', 5001, '/api/v0/');
const path = 'path/to/file.txt';
const content = 'Once upon a time, I wrote a brief novel. The end.';

ipfs.add(path, Buffer.from(content)).then(
  (hash) => console.log(hash)
).catch(
  (error) => console.log(error)
);

Fetch a text file

import { IpfsClient } from 'provide-js';

const ipfs = new IpfsClient('http', 'localhost', 5001, '/api/v0/');
const hash = 'hashIgotFromCreatingAfile';

ipfs.cat(hash).then(
  (fileBuffer) => console.log(fileBuffer.toString())
).catch(
  (error) => console.log(error)
);

Upload any kind of file

import { IpfsClient } from 'provide-js';
import fileReaderPullStream from 'pull-file-reader';

const ipfs = new IpfsClient('http', 'localhost', 5001, '/api/v0/');
// This event would come from an <input type='file'/> change event.
const file = event.target.files[0];
// Create a stream from the file, so big files may upload without allocating memory twice
const content = fileReaderPullStream(file);
const path = file.name;
let uploadProgress = '';
const options = {
  progress: (progress) => uploadProgress = `received: ${progress}`,
  wrapWithDirectory: true,
};

ipfs.add(path, content, options).then(
  (hash) => console.log(hash)
).catch(
  (error) => console.log(error)
);
// You may then download the file using your ipfs gateway url and hash,
// e.g. http://localhost:8080/ipfs/hashIgotFromCreatingAfile

IpfsClient with JavaScript and RxJS

Create a text file

import { Buffer } from 'buffer';
import { IpfsClient } from 'provide-js';
import { from } from 'rxjs';
import { first } from 'rxjs/operators';

const ipfs = new IpfsClient('http', 'localhost', 5001, '/api/v0/');
const path = 'path/to/file.txt';
const content = 'Once upon a time, I wrote a brief novel. The end.';
const observable = from(ipfs.add(path, Buffer.from(content)));

observable.pipe(first()).subscribe(
  (hash) => console.log(hash),
  (error) => console.log(error),
);

Fetch a text file

import { IpfsClient } from 'provide-js';
import { from } from 'rxjs';
import { first } from 'rxjs/operators';

const ipfs = new IpfsClient('http', 'localhost', 5001, '/api/v0/');
const hash = 'hashIgotFromCreatingAfile';
const observable = from(ipfs.cat(hash));

observable.pipe(first()).subscribe(
  (fileBuffer) => console.log(fileBuffer.toString()),
  (error) => console.log(error),
);

Upload any kind of file

import { IpfsClient } from 'provide-js';
import { from } from 'rxjs';
import { first } from 'rxjs/operators';
import fileReaderPullStream from 'pull-file-reader';

const ipfs = new IpfsClient('http', 'localhost', 5001, '/api/v0/');
// This event would come from an <input type='file'/> change event.
const file = event.target.files[0];
// Create a stream from the file, so big files may upload without allocating memory twice
const content = fileReaderPullStream(file);
const path = file.name;
let uploadProgress = '';
const options = {
  progress: (progress) => uploadProgress = `received: ${progress}`,
  wrapWithDirectory: true,
};
const observable = from(ipfs.add(path, content, options));

observable.pipe(first()).subscribe(
  (hash) => console.log(hash),
  (error) => console.log(error),
);
// You may then download the file using your ipfs gateway url and hash,
// e.g. http://localhost:8080/ipfs/hashIgotFromCreatingAfile

IpfsClient with TypeScript and Promise

Create a text file

import { Buffer } from 'buffer';
import { IpfsClient } from 'provide-js';

const ipfs: IpfsClient = new IpfsClient('http', 'localhost', 5001, '/api/v0/');
const path: string = 'path/to/file.txt';
const content: string = 'Once upon a time, I wrote a brief novel. The end.';

ipfs.add(path, Buffer.from(content)).then(
  (hash: string) => console.log(hash)
).catch(
  (error: Error) => console.log(error)
);

Fetch a text file

import { Buffer } from 'buffer';
import { IpfsClient } from 'provide-js';

const ipfs: IpfsClient = new IpfsClient('http', 'localhost', 5001, '/api/v0/');
const hash: string = 'hashIgotFromCreatingAfile';

ipfs.cat(hash).then(
  (fileBuffer: Buffer) => console.log(fileBuffer.toString())
).catch(
  (error: Error) => console.log(error)
);

Upload any kind of file

import { IpfsClient } from 'provide-js';
import fileReaderPullStream from 'pull-file-reader';

const ipfs = new IpfsClient('http', 'localhost', 5001, '/api/v0/');
// This event would come from an <input type='file'/> change event.
const file: File = event.target.files[0];
// Create a stream from the file, so big files may upload without allocating memory twice
const content: any = fileReaderPullStream(file);
const path: string = file.name;
let uploadProgress: string = '';
const options = {
  progress: (progress: number) => uploadProgress = `received: ${progress}`,
  wrapWithDirectory: true,
};

ipfs.add(path, content, options).then(
  (hash: string) => console.log(hash)
).catch(
  (error: Error) => console.log(error)
);
// You may then download the file using your ipfs gateway url and hash,
// e.g. http://localhost:8080/ipfs/hashIgotFromCreatingAfile

IpfsClient with TypeScript and RxJS

Create a text file

import { Buffer } from 'buffer';
import { IpfsClient } from 'provide-js';
import { from, Observable } from 'rxjs';
import { first } from 'rxjs/operators';

const ipfs: IpfsClient = new IpfsClient('http', 'localhost', 5001, '/api/v0/');
const path: string = 'path/to/file.txt';
const content: string = 'Once upon a time, I wrote a brief novel. The end.';
const observable: Observable<string | Error> = from(ipfs.add(path, Buffer.from(content)));

observable.pipe(first()).subscribe(
  (hash: string) => console.log(hash),
  (error: Error) => console.log(error),
);

Fetch a text file

import { Buffer } from 'buffer';
import { IpfsClient } from 'provide-js';
import { from, Observable } from 'rxjs';
import { first } from 'rxjs/operators';

const ipfs: IpfsClient = new IpfsClient('http', 'localhost', 5001, '/api/v0/');
const hash: string = 'hashIgotFromCreatingAfile';
const observable: Observable<Buffer | Error> = from(ipfs.cat(hash));

observable.pipe(first()).subscribe(
  (fileBuffer: Buffer) => console.log(fileBuffer.toString()),
  (error: Error) => console.log(error),
);

Upload any kind of file

import { IpfsClient } from 'provide-js';
import { from, Observable } from 'rxjs';
import { first } from 'rxjs/operators';
import fileReaderPullStream from 'pull-file-reader';

const ipfs: IpfsClient = new IpfsClient('http', 'localhost', 5001, '/api/v0/');
// This event would come from an <input type='file'/> change event.
const file: File = event.target.files[0];
// Create a stream from the file, so big files may upload without allocating memory twice
const content: any = fileReaderPullStream(file);
const path: string = file.name;
let uploadProgress: string = '';
const options = {
  progress: (progress: number) => uploadProgress = `received: ${progress}`,
  wrapWithDirectory: true,
};
const observable: Observable<string | Error> = from(ipfs.add(path, content, options));

observable.pipe(first()).subscribe(
  (hash: string) => console.log(hash),
  (error: Error) => console.log(error),
);
// You may then download the file using your ipfs gateway url and hash,
// e.g. http://localhost:8080/ipfs/hashIgotFromCreatingAfile