Merge pull request #645 from EOSIO/v20-merge

V20 merge

.travis.yml

@@ -28,3 +28,6 @@ deploy:
     on: 
       tags: true
       condition: $TRAVIS_IS_LATEST_TAG = true # sourced from ./scripts/is_latest.sh
+notifications:
+  webhooks:
+    secure: bBIpgJmtb4WbXgGTD71INlC7LqscHKOWZMiBmRtkUD1X9fjNzgNVKsjf4ZlTWpq9YtKFox0bAWjS00feRYlHZZal5tZEt9wRKJbkZEgnCa32YF2YOng0Q5JxoIBskH0SSUf/qocwjPmYQu+2Y3Y9KoLoV2C72qedGgSrrMmLWSVPA91tyqPl4gOU0HS6/9KU1QNf7Uv0v7Fo10+V+JwQC03MoC2+1dkz799LuUr2SmmN3JuLWSXl9KIq7CCF7wkcqzq1vMk176mmEH1/26InNXKLXIW/MqIjMfkZq4j+IjW+JbuWz/Qh3EY+rbQAMT+++tIYHNsh2wZppvAAPjf4vqO3m9Q4WBB2KbL6EDvE/ySDURxLzZl618u8WUbJh2o61k0R0rxPPl6yFdkl9jXV48IVTHEDYHkgghtLSSENMUmjK8kshA2qreG79Mj2l2jicZ5Vn7jv4iORQHS0PUXg4ouds+5dY0SPm9aLIop6f9WD0mcQFP9mEfagWA6EnGUxTPFQDQmNVGkpZk2afYNAT4LbOd8wrqDTsNWXRvA3QLLOiqBbhajY17Fvrh24ecJ79TERABLscFkYtke8Xx2K/lKg/T10TZuaL9VbTg4rKrD+59OTZev6JlNdGG8FR31SuJK8Ds3zmiyojCoCay54BDUbmZ0STJ1/6ocUvFka0YE=

README.md

@@ -15,6 +15,21 @@ The official distribution package can be found at [npm](https://www.npmjs.com/pa
 
 `yarn add eosjs`
 
+### Using with Typescript
+
+In order to get access to the `TextEncoding` and `TextDecoding` types, you need to add `@types/text-encoding` as a dev dependency:
+`yarn add --dev @types/text-encoding`
+
+If you're using Node (not a browser) then you'll also need to make sure the `dom` lib is referenced in your `tsconfig.json`:
+
+```
+{
+	"compilerOptions": {
+		"lib": [..., "dom"]
+	}
+}
+```
+
 ### Browser Distribution
 
 Clone this repository locally then run `yarn build-web`.  The browser distribution will be located in `dist-web` and can be directly copied into your project repository. The `dist-web` folder contains minified bundles ready for production, along with source mapped versions of the library for debugging.  For full browser usage examples, [see the documentation](https://eosio.github.io/eosjs/guides/1.-Browsers.html).
@@ -124,4 +139,6 @@ try {
 
 ## Important
 
-See LICENSE for copyright and license terms.  Block.one makes its contribution on a voluntary basis as a member of the EOSIO community and is not responsible for ensuring the overall performance of the software or any related applications.  We make no representation, warranty, guarantee or undertaking in respect of the software or any related documentation, whether expressed or implied, including but not limited to the warranties or merchantability, fitness for a particular purpose and noninfringement. In no event shall we be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or documentation or the use or other dealings in the software or documentation.  Any test results or performance figures are indicative and will not reflect performance under all conditions.  Any reference to any third party or third-party product, service or other resource is not an endorsement or recommendation by Block.one.  We are not responsible, and disclaim any and all responsibility and liability, for your use of or reliance on any of these resources. Third-party resources may be updated, changed or terminated at any time, so the information here may be out of date or inaccurate.
+See LICENSE for copyright and license terms.  Block.one makes its contribution on a voluntary basis as a member of the EOSIO community and is not responsible for ensuring the overall performance of the software or any related applications.  We make no representation, warranty, guarantee or undertaking in respect of the software or any related documentation, whether expressed or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall we be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or documentation or the use or other dealings in the software or documentation. Any test results or performance figures are indicative and will not reflect performance under all conditions.  Any reference to any third party or third-party product, service or other resource is not an endorsement or recommendation by Block.one.  We are not responsible, and disclaim any and all responsibility and liability, for your use of or reliance on any of these resources. Third-party resources may be updated, changed or terminated at any time, so the information here may be out of date or inaccurate.  Any person using or offering this software in connection with providing software, goods or services to third parties shall advise such third parties of these license terms, disclaimers and exclusions of liability.  Block.one, EOSIO, EOSIO Labs, EOS, the heptahedron and associated logos are trademarks of Block.one.
+
+Wallets and related components are complex software that require the highest levels of security.  If incorrectly built or used, they may compromise users’ private keys and digital assets. Wallet applications and related components should undergo thorough security evaluations before being used.  Only experienced developers should work with this software.

docs.json

@@ -0,0 +1,46 @@
+{
+	"name": "eosjs",
+	"generators": [
+    {
+			"name": "collate_markdown",
+			"options": {
+				"docs_dir": "docs"
+			}
+		},
+		{
+			"name": "typedoc",
+			"options": {
+        "theme": "markdown",
+        "exclude": ["**/index*","**/*.test.ts","**/rpc-web*"],
+        "ignoreCompilerErrors": true,
+        "includeDeclarations": false,
+        "excludeExternals": true,
+        "excludeProtected": true,
+        "excludePrivate": true,
+        "typescript": {
+          "include": [
+            "src/**/*.js"
+          ]
+        }
+      }
+		}
+	],
+  "filters": [
+    {
+      "name": "search_replace",
+      "options": {
+        "search": "numeric.md#",
+        "replace": "#",
+        "filepattern": "numeric.md"
+      }
+    },
+    {
+      "name": "search_replace",
+      "options": {
+        "search": "serialize.md#",
+        "replace": "#",
+        "filepattern": "serialize.md"
+      }
+    }
+  ]
+}

docs/00_introduction.md

@@ -0,0 +1,8 @@
+`eosjs` is a Javascript library which provides an API for integrating with EOSIO-based blockchains using the [EOSIO Nodeos RPC API](https://developers.eos.io/eosio-nodeos/reference).  The documentation for `eosjs` is structured in the following way:
+
+* [Installation](02_installation.md) explains how to install `eosjs` using `npm` or `yarn`.
+* [Basic Usage](basic-usage/) provides information related to importing `eosjs` in various Javascript environments.  The [basic-usage](basic-usage/03_basic-usage.md) document specifically provides brief explanations of the components provided by `eosjs` as well as their typical use cases.
+* [FAQ](faq/) provides answers to frequently asked questions surrounding the `eosjs` software.
+* [How-To Guides](how-to-guides/) provides how-tos on everything from getting block information to proposing and signing multi-sig transactions.
+* [Troubleshooting](troubleshooting/) provides possible exceptions encountered when developing with `eosjs` and their most common causes.
+* [Technical Overview](01_technical-overview.md) provides a high-level overview of how `eosjs` works.

docs/01_technical-overview.md

@@ -0,0 +1,23 @@
+As stated in the [introduction](00_introduction.md), `eosjs` integrates with EOSIO-based blockchains using the [EOSIO Nodeos RPC API](https://developers.eos.io/eosio-nodeos/reference).
+
+In general, there are two objects that are used to interact with a blockchain via `eosjs`: the `JsonRpc` object, and the `Api` object.
+
+## JsonRpc
+The `JsonRpc` object is typically used when signing is not necessary.  Some examples include [getting block information](how-to-guides/00_how-to-get-block-information.md), [getting transaction information](how-to-guides/02_how-to-get-transaction-information.md), or [getting table information](how-to-guides/09_how-to-get-table-information.md).  
+
+The requests made by the `JsonRpc` object will either use a built-in `fetch` library, or [the `fetch` library passed in by the user](basic-usage/01_commonjs.md) to issue requests to the endpoint specified when instantiating the `JsonRpc` object.  When the various methods ([get_abi](https://github.com/EOSIO/eosjs/blob/master/src/eosjs-jsonrpc.ts#L66), [get_account](https://github.com/EOSIO/eosjs/blob/master/src/eosjs-jsonrpc.ts#L71), [get_block_header_state](https://github.com/EOSIO/eosjs/blob/master/src/eosjs-jsonrpc.ts#L76), etc) of the `JsonRpc` object are invoked, the calls are delegated to the `JsonRpc` object's [fetch function](https://github.com/EOSIO/eosjs/blob/master/src/eosjs-jsonrpc.ts#L42-L63), which in turn, delegate the requests to the `fetch` library.
+
+## Api
+The `Api` object is typically used when transacting on an EOSIO-based blockchain.  Some examples include [staking](how-to-guides/03_how-to-stake.md), [creating an account](how-to-guides/05_how-to-create-an-account.md), or [proposing multi-sig transactions](how-to-guides/13_how-to-propose-a-multisig-transaction.md).
+
+The typical use of the `Api` object is to call its [`transact` method](https://github.com/EOSIO/eosjs/blob/master/src/eosjs-api.ts#L214-L254).  This method performs a number of steps depending on the input passed to it:
+
+* The `transact` method first checks if the **chainId** was set in the `Api` constructor, and if not, uses the [`JsonRpc` object's](#jsonrpc) [`get_info`](https://github.com/EOSIO/eosjs/blob/master/src/eosjs-jsonrpc.ts#L101) method to retrieve the **chainId**.  
+* The `transact` method then checks if the `blocksBehind` and `expiration` fields are set and well-formed in the [optional configuration object, as specified in *How to Submit a Transaction*](how-to-guides/01_how-to-submit-a-transaction.md#).  
+    * If so, the block *blocksBehind* the head block retrieved from [`JsonRpc`'s `get_info`](https://github.com/EOSIO/eosjs/blob/master/src/eosjs-jsonrpc.ts#L101) is set as the reference block and the transaction header is serialized using this reference block and the `expiration` field.
+* The `transact` method then checks if the appropriate TAPOS fields are present in the transaction ([they can either be specified directly in the transaction or in the optional configuration object](how-to-guides/01_how-to-submit-a-transaction.md#)) and throws an Error if not.
+* The necessary `abi`s for a transaction are then retrieved for the case when `transact` is expected to sign the transaction.
+* The `actions` are serialized using the `eosjs-serialize` `ser` object.
+* The entire transaction is then [serialized](https://github.com/EOSIO/eosjs/blob/master/src/eosjs-api.ts#L154-L166), also using the `eosjs-serialize` `ser` object.
+* The transaction is then optionally signed, using the `signatureProvider`, the previously retrieved `abi`s, the private keys of the `signatureProvider`, and the `chainId`.
+* The transaction is then optionally broadcasted using `JsonRpc`'s [`push_transaction`](https://github.com/EOSIO/eosjs/blob/master/src/eosjs-jsonrpc.ts#L187).

docs/02_installation.md

@@ -0,0 +1,9 @@
+`eosjs` can be installed via [`yarn`](https://yarnpkg.com/en/)
+```javascript
+yarn add eosjs
+```
+
+or [`npm`](https://www.npmjs.com/)
+```javascript
+npm install eosjs
+```