add api docs (#239)

.github/workflows/build-and-deploy-docs.yml

@@ -0,0 +1,24 @@
+name: Build and Deploy Docs
+on:
+  push:
+    branches:
+      - master
+jobs:
+  build-and-deploy-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/[email protected]
+
+      - name: Install and Build 🔧
+        run: |
+          yarn
+          yarn bootstrap
+          yarn build
+          yarn docs
+
+      - name: Deploy Docs 🚀
+        uses: JamesIves/[email protected]
+        with:
+          branch: docs
+          folder: docs

.gitignore

@@ -4,4 +4,5 @@ node_modules
 build
 coverage
 .idea
-*.tgz
+*.tgz
+docs/

README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img width="120" height="120" src="https://github.com/helium/helium-js/blob/master/icon.png">
+  <img width="120" height="120" src="https://raw.githubusercontent.com/helium/helium-js/master/icon.png">
 </p>
 
 # Helium JS SDK
@@ -8,17 +8,19 @@
 [![Coverage Status](https://coveralls.io/repos/github/helium/helium-js/badge.svg?branch=master)](https://coveralls.io/github/helium/helium-js?branch=master)
 [![Renovate](https://img.shields.io/badge/renovate-enabled-brightgreen.svg)](https://renovatebot.com)
 
-> :warning: These libraries are currently in active development and are provided as-is. Helium makes no claims or guarantees about the correctness, reliability or security of this code. PRs welcome, see [CONTRIBUTING](https://github.com/heilum/helium-js/blob/master/CONTRIBUTING.md).
+Please view the [Documentation](https://helium.github.io/helium-js/) for usage and examples.
 
+> ⚠️ These libraries are currently in active development and are provided as-is. Helium makes no claims or guarantees about the correctness, reliability or security of this code. PRs welcome, see [CONTRIBUTING](https://github.com/helium/helium-js/blob/master/CONTRIBUTING.md).
 
-This SDK is a collection of TypeScrypt libraries for interacting with the Helium blockchain. For additional documentation about the Helium network, visit the [Developer Site](https://developer.helium.com).
+
+This SDK is a collection of TypeScrypt libraries for interacting with the Helium blockchain. For additional documentation about the Helium network, visit the [Developer Site](https://docs.helium.com/).
 
 
 | Package | NPM Version | What it's for |
 |-------------------------------------------------------------------------------------------------|-----------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|
 | [`@helium/crypto`](https://github.com/helium/helium-js/tree/master/packages/crypto) | ![npm](https://img.shields.io/npm/v/@helium/crypto) | Cryptography utilities including keypairs, mnemonics and base58-check encoding |
 | [`@helium/crypto-react-native`](https://github.com/helium/helium-js/tree/master/packages/crypto-react-native) | ![npm](https://img.shields.io/npm/v/@helium/crypto-react-native) | Cryptography utilities following the same interface as `@helium/crypto` but for React Native |
-| [`@helium/transactions`](https://github.com/helium/helium-js/tree/master/packages/transactions) | ![npm](https://img.shields.io/npm/v/@helium/transactions) | Construct and serialize transaction primatives from their [protobuf](https://developers.google.com/protocol-buffers) definitions |
+| [`@helium/transactions`](https://github.com/helium/helium-js/tree/master/packages/transactions) | ![npm](https://img.shields.io/npm/v/@helium/transactions) | Construct and serialize transaction primitives from their [protobuf](https://developers.google.com/protocol-buffers) definitions |
 | [`@helium/proto`](https://github.com/helium/proto) | ![npm](https://img.shields.io/npm/v/@helium/proto) | Protobuf definitions for Helium transactions |
 | [`@helium/http`](https://github.com/helium/helium-js/tree/master/packages/http) | ![npm](https://img.shields.io/npm/v/@helium/http) | An HTTP client for the blockchain REST API |
 | [`@helium/currency`](https://github.com/helium/helium-js/tree/master/packages/currency) | ![npm](https://img.shields.io/npm/v/@helium/currency) | Utilities for representing amounts of the different currencies supported by Helium |
@@ -129,7 +131,7 @@ client.transactions.submit(signedPaymentTxn.toString())
 ```
 
 ### Sending an Account's full balance
-Sending the maximum amount from an account (leaving a 0 HNT balance) requires taking into account the transaction fee. All fees are denominated in Data Credits (DC), which is equal to $0.00001 USD, meaning 35,000 DC equals $0.35 USD. DC are obtained by _burning_ HNT, permanantly removing it from circulation. If you do not already have DC in your account, the appropriate amount of HNT will be burned to cover the fee.
+Sending the maximum amount from an account (leaving a 0 HNT balance) requires taking into account the transaction fee. All fees are denominated in Data Credits (DC), which is equal to $0.00001 USD, meaning 35,000 DC equals $0.35 USD. DC are obtained by _burning_ HNT, permanently removing it from circulation. If you do not already have DC in your account, the appropriate amount of HNT will be burned to cover the fee.
 
 The general formula is:
 `amountToSend = balance - feeInHNT`
@@ -197,5 +199,5 @@ client.transactions.submit(signedPaymentTxn.toString())
 
 ```
 
-> :warning: Note that oracle prices change over time. It's possible for a transaction to fail if the oracle price changes in between the time the transaction is conrstructed and when it is absorbed by the consensus group. The API exposes what the next oracle price will be at `https://api.helium.io
-/v1/oracle/predictions`. See https://developer.helium.com/blockchain/api/oracle for more details. To avoid failed transactions, it may be worth querying both the oracle predictions, and the current oracle value, and taking the greater of those values.
+> ⚠️ Note that oracle prices change over time. It's possible for a transaction to fail if the oracle price changes in between the time the transaction is constructed and when it is absorbed by the consensus group. The API exposes what the next oracle price will be at `https://api.helium.io
+/v1/oracle/predictions`. See https://developer.helium.com/blockchain/api/oracle for more details. To avoid failed transactions, it may be worth querying both the oracle predictions, and the current oracle value, and taking the greatest of those values.

package.json

@@ -8,7 +8,8 @@
     "lint": "eslint --ext .ts ./",
     "format": "prettier-standard --format",
     "coveralls": "cat ./coverage/lcov.info | coveralls",
-    "preversion": "yarn build"
+    "preversion": "yarn build",
+    "docs": "typedoc"
   },
   "jest": {
     "preset": "ts-jest",
@@ -37,6 +38,7 @@
     "rimraf": "3.0.2",
     "standard": "16.0.3",
     "ts-jest": "26.4.4",
+    "typedoc": "^0.22.4",
     "typescript": "4.1.2"
   }
 }

packages/crypto-react-native/src/index.ts

@@ -1,3 +1,9 @@
+/**
+ * [[include:crypto-react-native/README.md]]
+ * @packageDocumentation
+ * @module crypto-react-native
+ */
+
 export { default as Mnemonic } from './Mnemonic'
 export { default as Keypair } from './Keypair'
 export { default as Address } from './Address'

packages/crypto/src/index.ts

@@ -1,3 +1,9 @@
+/**
+ * [[include:crypto/README.md]]
+ * @packageDocumentation
+ * @module crypto
+ */
+
 export { default as Mnemonic } from './Mnemonic'
 export { default as Keypair } from './Keypair'
 export { default as Address } from './Address'

packages/currency/src/index.ts

@@ -1,3 +1,9 @@
+/**
+ * [[include:currency/README.md]]
+ * @packageDocumentation
+ * @module currency
+ */
+
 export { default as Balance } from './Balance'
 export { default as CurrencyType, AnyCurrencyType } from './CurrencyType'
 export { NetworkTokens, DataCredits, SecurityTokens, USDollars } from './currency_types'

packages/http/src/index.ts

@@ -1,3 +1,9 @@
+/**
+ * [[include:http/README.md]]
+ * @packageDocumentation
+ * @module http
+ */
+
 export { default as Client } from './Client'
 export { default } from './Client'
 export { default as Network } from './Network'

packages/transactions/src/index.ts

@@ -1,4 +1,9 @@
 /* eslint-disable import/prefer-default-export */
+/**
+ * [[include:transactions/README.md]]
+ * @packageDocumentation
+ * @module transactions
+ */
 export { default as Transaction } from './Transaction'
 export { default as PaymentV1 } from './PaymentV1'
 export { default as PaymentV2 } from './PaymentV2'
@@ -7,3 +12,4 @@ export { default as AssertLocationV1 } from './AssertLocationV1'
 export { default as AssertLocationV2 } from './AssertLocationV2'
 export { default as TokenBurnV1 } from './TokenBurnV1'
 export { default as TransferHotspotV1 } from './TransferHotspotV1'
+export * from './types'

typedoc.json

@@ -0,0 +1,17 @@
+{
+  "entryPoints": [
+    "packages/crypto/src/index.ts",
+    "packages/crypto-react-native/src/index.ts",
+    "packages/currency/src/index.ts",
+    "packages/http/src/index.ts",
+    "packages/proto-ble/build/index.d.ts",
+    "packages/transactions/src/index.ts"
+  ],
+  "exclude": [
+    "**/*.spec.ts"
+  ],
+  "includes": "packages",
+  "name": "Helium JS",
+  "out": "docs",
+  "readme": "README.md"
+}

yarn.lock

@@ -4294,6 +4294,18 @@ glob@^7.0.3, glob@^7.1.1, glob@^7.1.2, glob@^7.1.3, glob@^7.1.4:
     once "^1.3.0"
     path-is-absolute "^1.0.0"
 
+glob@^7.1.7:
+  version "7.2.0"
+  resolved "https://registry.yarnpkg.com/glob/-/glob-7.2.0.tgz#d15535af7732e02e948f4c41628bd910293f6023"
+  integrity sha512-lmLf6gtyrPq8tTjSmrO94wBeQbFR3HbLHbuyD69wuyQkImp2hWqMGB47OX65FBkPffO641IP9jWa1z4ivqG26Q==
+  dependencies:
+    fs.realpath "^1.0.0"
+    inflight "^1.0.4"
+    inherits "2"
+    minimatch "^3.0.4"
+    once "^1.3.0"
+    path-is-absolute "^1.0.0"
+
 globals@^11.1.0:
   version "11.12.0"
   resolved "https://registry.yarnpkg.com/globals/-/globals-11.12.0.tgz#ab8795338868a0babd8525758018c2a7eb95c42e"
@@ -5701,6 +5713,11 @@ json5@^1.0.1:
   dependencies:
     minimist "^1.2.0"
 
+jsonc-parser@^3.0.0:
+  version "3.0.0"
+  resolved "https://registry.yarnpkg.com/jsonc-parser/-/jsonc-parser-3.0.0.tgz#abdd785701c7e7eaca8a9ec8cf070ca51a745a22"
+  integrity sha512-fQzRfAbIBnR0IQvftw9FJveWiHp72Fg20giDrHz6TdfB12UH/uue0D3hm57UB5KgAVuniLMCaS8P1IMj9NR7cA==
+
 jsonfile@^4.0.0:
   version "4.0.0"
   resolved "https://registry.yarnpkg.com/jsonfile/-/jsonfile-4.0.0.tgz#8771aae0799b64076b76640fca058f9c10e33ecb"
@@ -6087,6 +6104,11 @@ lru-cache@^5.1.1:
   dependencies:
     yallist "^3.0.2"
 
+lunr@^2.3.9:
+  version "2.3.9"
+  resolved "https://registry.yarnpkg.com/lunr/-/lunr-2.3.9.tgz#18b123142832337dd6e964df1a5a7707b25d35e1"
+  integrity sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==
+
 macos-release@^2.2.0:
   version "2.4.1"
   resolved "https://registry.yarnpkg.com/macos-release/-/macos-release-2.4.1.tgz#64033d0ec6a5e6375155a74b1a1eba8e509820ac"
@@ -6182,6 +6204,11 @@ markdown-escapes@^1.0.0:
   resolved "https://registry.yarnpkg.com/markdown-escapes/-/markdown-escapes-1.0.4.tgz#c95415ef451499d7602b91095f3c8e8975f78535"
   integrity sha512-8z4efJYk43E0upd0NbVXwgSTQs6cT3T06etieCMEg7dRbzCbxUCK/GHlX8mhHRDcp+OLlHkPKsvqQTCvsRl2cg==
 
+marked@^3.0.4:
+  version "3.0.4"
+  resolved "https://registry.yarnpkg.com/marked/-/marked-3.0.4.tgz#b8a1539e5e05c6ea9e93f15c0bad1d54ce890406"
+  integrity sha512-jBo8AOayNaEcvBhNobg6/BLhdsK3NvnKWJg33MAAPbvTWiG4QBn9gpW1+7RssrKu4K1dKlN+0goVQwV41xEfOA==
+
 [email protected]:
   version "5.1.1"
   resolved "https://registry.yarnpkg.com/mem/-/mem-5.1.1.tgz#7059b67bf9ac2c924c9f1cff7155a064394adfb3"
@@ -6802,6 +6829,13 @@ onetime@^5.1.0:
   dependencies:
     mimic-fn "^2.1.0"
 
+onigasm@^2.2.5:
+  version "2.2.5"
+  resolved "https://registry.yarnpkg.com/onigasm/-/onigasm-2.2.5.tgz#cc4d2a79a0fa0b64caec1f4c7ea367585a676892"
+  integrity sha512-F+th54mPc0l1lp1ZcFMyL/jTs2Tlq4SqIHKIXGZOR/VkHkF9A7Fr5rRr5+ZG/lWeRsyrClLYRq7s/yFQ/XhWCA==
+  dependencies:
+    lru-cache "^5.1.1"
+
 optionator@^0.8.1, optionator@^0.8.3:
   version "0.8.3"
   resolved "https://registry.yarnpkg.com/optionator/-/optionator-0.8.3.tgz#84fa1d036fe9d3c7e21d99884b601167ec8fb495"
@@ -8098,6 +8132,15 @@ shellwords@^0.1.1:
   resolved "https://registry.yarnpkg.com/shellwords/-/shellwords-0.1.1.tgz#d6b9181c1a48d397324c84871efbcfc73fc0654b"
   integrity sha512-vFwSUfQvqybiICwZY5+DAWIPLKsWO31Q91JSKl3UYv+K5c2QRPzn0qzec6QPu1Qc9eHYItiP3NdJqNVqetYAww==
 
+shiki@^0.9.11:
+  version "0.9.11"
+  resolved "https://registry.yarnpkg.com/shiki/-/shiki-0.9.11.tgz#07d75dab2abb6dc12a01f79a397cb1c391fa22d8"
+  integrity sha512-tjruNTLFhU0hruCPoJP0y+B9LKOmcqUhTpxn7pcJB3fa+04gFChuEmxmrUfOJ7ZO6Jd+HwMnDHgY3lv3Tqonuw==
+  dependencies:
+    jsonc-parser "^3.0.0"
+    onigasm "^2.2.5"
+    vscode-textmate "5.2.0"
+
 side-channel@^1.0.2:
   version "1.0.3"
   resolved "https://registry.yarnpkg.com/side-channel/-/side-channel-1.0.3.tgz#cdc46b057550bbab63706210838df5d4c19519c3"
@@ -8983,6 +9026,17 @@ typedarray@^0.0.6:
   resolved "https://registry.yarnpkg.com/typedarray/-/typedarray-0.0.6.tgz#867ac74e3864187b1d3d47d996a78ec5c8830777"
   integrity sha1-hnrHTjhkGHsdPUfZlqeOxciDB3c=
 
+typedoc@^0.22.4:
+  version "0.22.4"
+  resolved "https://registry.yarnpkg.com/typedoc/-/typedoc-0.22.4.tgz#039ac59fcdb9a8674471dc20e1623efb12be4114"
+  integrity sha512-M/a8NnPxq3/iZNNVjzFCK5gu4m//HTJIPbSS0JQVbkHJPP9wyepR12agylWTSqeVZe0xsbidVtO26+PP7iD/jw==
+  dependencies:
+    glob "^7.1.7"
+    lunr "^2.3.9"
+    marked "^3.0.4"
+    minimatch "^3.0.4"
+    shiki "^0.9.11"
+
 [email protected]:
   version "4.1.2"
   resolved "https://registry.yarnpkg.com/typescript/-/typescript-4.1.2.tgz#6369ef22516fe5e10304aae5a5c4862db55380e9"
@@ -9238,6 +9292,11 @@ [email protected]:
     leven "^2.1.0"
     tslib "^1.9.3"
 
+[email protected]:
+  version "5.2.0"
+  resolved "https://registry.yarnpkg.com/vscode-textmate/-/vscode-textmate-5.2.0.tgz#01f01760a391e8222fe4f33fbccbd1ad71aed74e"
+  integrity sha512-Uw5ooOQxRASHgu6C7GVvUxisKXfSgW4oFlO+aa+PAkgmH89O3CXxEEzNRNtHSqtXFTl0nAC1uYj0GMSH27uwtQ==
+
 w3c-hr-time@^1.0.2:
   version "1.0.2"
   resolved "https://registry.yarnpkg.com/w3c-hr-time/-/w3c-hr-time-1.0.2.tgz#0a89cdf5cc15822df9c360543676963e0cc308cd"