diff --git a/.github/workflows/build-and-deploy-docs.yml b/.github/workflows/build-and-deploy-docs.yml new file mode 100644 index 00000000..bf215189 --- /dev/null +++ b/.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/checkout@v2.3.1 + + - name: Install and Build 🔧 + run: | + yarn + yarn bootstrap + yarn build + yarn docs + + - name: Deploy Docs 🚀 + uses: JamesIves/github-pages-deploy-action@4.1.5 + with: + branch: docs + folder: docs diff --git a/.gitignore b/.gitignore index f0fafc94..1c8528a6 100644 --- a/.gitignore +++ b/.gitignore @@ -4,4 +4,5 @@ node_modules build coverage .idea -*.tgz \ No newline at end of file +*.tgz +docs/ diff --git a/README.md b/README.md index 2b197604..e1f5aec0 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@

- +

# 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. diff --git a/package.json b/package.json index 957970d7..c563487a 100644 --- a/package.json +++ b/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" } } diff --git a/packages/crypto-react-native/src/index.ts b/packages/crypto-react-native/src/index.ts index 0b686837..88799f5c 100644 --- a/packages/crypto-react-native/src/index.ts +++ b/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' diff --git a/packages/crypto/src/index.ts b/packages/crypto/src/index.ts index 1f93da3a..d6f0d828 100644 --- a/packages/crypto/src/index.ts +++ b/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' diff --git a/packages/currency/src/index.ts b/packages/currency/src/index.ts index e8bcbc68..0fc85fc5 100644 --- a/packages/currency/src/index.ts +++ b/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' diff --git a/packages/http/src/index.ts b/packages/http/src/index.ts index c12f8d2d..e47dfe04 100644 --- a/packages/http/src/index.ts +++ b/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' diff --git a/packages/transactions/src/index.ts b/packages/transactions/src/index.ts index 1aafb29e..05aa99e0 100644 --- a/packages/transactions/src/index.ts +++ b/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' diff --git a/typedoc.json b/typedoc.json new file mode 100644 index 00000000..57415db0 --- /dev/null +++ b/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" +} diff --git a/yarn.lock b/yarn.lock index bd2f0561..f9dce600 100644 --- a/yarn.lock +++ b/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== + mem@5.1.1: 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" + typescript@4.1.2: version "4.1.2" resolved "https://registry.yarnpkg.com/typescript/-/typescript-4.1.2.tgz#6369ef22516fe5e10304aae5a5c4862db55380e9" @@ -9238,6 +9292,11 @@ vnopts@1.0.2: leven "^2.1.0" tslib "^1.9.3" +vscode-textmate@5.2.0: + 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"