Merge pull request #528 from EOSIO/develop

Prepare for v20 release

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,17 @@
+<!-- PLEASE FILL OUT THE FOLLOWING MARKDOWN TEMPLATE -->
+<!-- PR title alone should be sufficient to understand changes. -->
+
+## Change Description
+<!-- Describe your changes, their justification, AND their impact. Reference issues or pull requests where possible (use '#XX' or 'GH-XX' where XX is the issue or pull request number). -->
+
+
+## API Changes
+- [ ] API Changes
+<!-- checked [x] = API changes; unchecked [ ] = no changes, ignore this section -->
+<!-- If this PR introduces API changes, please describe the changes here. What will developers need to know before upgrading to this version? -->
+
+
+## Documentation Additions
+- [ ] Documentation Additions
+<!-- checked [x] = Documentation changes; unchecked [ ] = no changes, ignore this section -->
+<!-- Describe what must be added to the documentation after merge. -->

.gitignore

@@ -3,3 +3,9 @@ dist/
 dist-web/
 node_modules/
 docs-build/
+*.tgz
+
+#cypress artifacts
+cypress/screenshots/
+cypress/videos/
+reports/

.npmignore

@@ -0,0 +1,12 @@
+# Exclude all files by default
+*
+
+# Include distribution bundle but exclude test files if they are built into dist
+!dist/**
+*.test.*
+
+# Include documentation and version information in bundle
+!CONTRIBUTING.md
+
+# Include any additional source files which should be bundled
+!src/**/*.abi.json

.travis.yml

@@ -27,4 +27,4 @@ deploy:
       - ./scripts/publish-tag.sh $PUBLISH_NPM_LATEST_FROM
     on: 
       tags: true
-      condition: $TRAVIS_IS_LATEST_TAG = true # sourced from ./scripts/is_latest.sh
+      condition: $TRAVIS_IS_LATEST_TAG = true # sourced from ./scripts/is_latest.sh

CONTRIBUTING.md

@@ -0,0 +1,169 @@
+# Contributing to EOSJS
+
+Interested in contributing? That's awesome! Here are some guidelines to get started quickly and easily:
+
+- [Reporting An Issue](#reporting-an-issue)
+  - [Bug Reports](#bug-reports)
+  - [Feature Requests](#feature-requests)
+  - [Change Requests](#change-requests)
+- [Working on EOSJS](#working-on-eosjs)
+  - [Feature Branches](#feature-branches)
+  - [Submitting Pull Requests](#submitting-pull-requests)
+  - [Testing](#testing)
+  - [Quality Assurance](#quality-assurance)
+- [Conduct](#conduct)
+- [Contributor License & Acknowledgments](#contributor-license--acknowledgments)
+- [References](#references)
+
+## Reporting An Issue
+
+If you're about to raise an issue because you think you've found a problem with EOSJS, or you'd like to make a request for a new feature in the codebase, or any other reason… please read this first.
+
+The GitHub issue tracker is the preferred channel for [bug reports](#bug-reports), [feature requests](#feature-requests), and [submitting pull requests](#submitting-pull-requests), but please respect the following restrictions:
+
+* Please **search for existing issues**. Help us keep duplicate issues to a minimum by checking to see if someone has already reported your problem or requested your idea.
+
+* Please **be civil**. Keep the discussion on topic and respect the opinions of others. See also our [Contributor Code of Conduct](#conduct).
+
+### Bug Reports
+
+A bug is a _demonstrable problem_ that is caused by the code in the repository. Good bug reports are extremely helpful - thank you!
+
+Guidelines for bug reports:
+
+1. **Use the GitHub issue search** — check if the issue has already been
+   reported.
+
+1. **Check if the issue has been fixed** — look for [closed issues in the
+   current milestone](https://github.com/EOSIO/eosjs/issues?q=is%3Aissue+is%3Aclosed) or try to reproduce it
+   using the latest `develop` branch.
+
+A good bug report shouldn't leave others needing to chase you up for more information. Be sure to include the details of your environment and relevant tests that demonstrate the failure.
+
+[Report a bug](https://github.com/EOSIO/eosjs/issues/new?template=bug_report.md)
+
+### Feature Requests
+
+Feature requests are welcome. Before you submit one be sure to have:
+
+1. **Use the GitHub search** and check the feature hasn't already been requested.
+1. Take a moment to think about whether your idea fits with the scope and aims of the project.
+1. Remember, it's up to *you* to make a strong case to convince the project's leaders of the merits of this feature. Please provide as much detail and context as possible, this means explaining the use case and why it is likely to be common.
+
+### Change Requests
+
+Change requests cover both architectural and functional changes to how EOSJS works. If you have an idea for a new or different dependency, a refactor, or an improvement to a feature, etc - please be sure to:
+
+1. **Use the GitHub search** and check someone else didn't get there first
+1. Take a moment to think about the best way to make a case for, and explain what you're thinking. Are you sure this shouldn't really be
+   a [bug report](#bug-reports) or a [feature request](#feature-requests)?  Is it really one idea or is it many? What's the context? What problem are you solving? Why is what you are suggesting better than what's already there?
+
+## Working on EOSJS
+
+Code contributions are welcome and encouraged! If you are looking for a good place to start, check out the [good first issue](https://github.com/EOSIO/eosjs/labels/good%20first%20issue) label in GitHub issues.
+
+Also, please follow these guidelines when submitting code:
+
+### Feature Branches
+
+To get it out of the way:
+
+- **[develop](https://github.com/EOSIO/eosjs/tree/develop)** is the development branch. All work on the next release happens here so you should generally branch off `develop`. Do **NOT** use this branch for a production site.
+- **[master](https://github.com/EOSIO/eosjs/tree/master)** contains the latest release of EOSJS. This branch may be used in production. Do **NOT** use this branch to work on EOSJS's source.
+
+### Submitting Pull Requests
+
+Pull requests are awesome. If you're looking to raise a PR for something which doesn't have an open issue, please think carefully about [raising an issue](#reporting-an-issue) which your PR can close, especially if you're fixing a bug. This makes it more likely that there will be enough information available for your PR to be properly tested and merged.
+
+### Testing
+
+EOSJS is used by many libraries across the EOSIO ecosystem, so proper testing is absolutely essential prior to opening a pull request. This can be done in EOSJS by running `yarn build-production`.  This command will build the distrubution bundles (`yarn build-all`) and test each environment accordingly (`yarn test-all`).
+
+#### Automated Unit Test Suite
+
+`yarn test` will run through the core functionality of each EOSJS module with Jest.
+
+#### Integration Test Suite
+
+Integration tests will only work with a local node running on port 8888 and with test accounts "bob" and "alice".  This can be accomplished by following the [EOSIO Developer Getting Started Guide](https://developers.eos.io/eosio-home/docs/getting-the-software#section-step-1-1-start-keosd).
+
+##### Web Environment
+
+Run `yarn build-web` to create the `dist-web` folder and web distrubution modules then `yarn test-web`.  This will run through the `tests/web.html` file using Cypress to inform you on the command line of any test failures.
+
+##### NodeJS Environment
+
+Run `yarn build` to build the NPM distribution bundle then run `yarn test-node`.  This will create an out of box node environment with `tests/node.js` then test that environment with Jest and relay the results to the command line.
+
+### Quality Assurance
+
+Never underestimate just how useful quality assurance is. If you're looking to get involved with the code base and don't know where to start, checking out and testing a pull request is one of the most useful things you could do.
+
+Essentially, [check out the latest develop branch](#working-on-eosjs), take it for a spin, and if you find anything odd, please follow the [bug report guidelines](#bug-reports) and let us know!
+
+## Conduct
+
+While contributing, please be respectful and constructive, so that participation in our project is a positive experience for everyone.
+
+Examples of behavior that contributes to creating a positive environment include:
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior include:
+- The use of sexualized language or imagery and unwelcome sexual attention or advances
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others’ private information, such as a physical or electronic address, without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Contributor License & Acknowledgments
+
+Whenever you make a contribution to this project, you license your contribution under the same terms as set out in LICENSE, and you represent and warrant that you have the right to license your contribution under those terms.  Whenever you make a contribution to this project, you also certify in the terms of the Developer’s Certificate of Origin set out below:
+
+```
+Developer Certificate of Origin
+Version 1.1
+
+Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+1 Letterman Drive
+Suite D4700
+San Francisco, CA, 94129
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+    have the right to submit it under the open source license
+    indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+    of my knowledge, is covered under an appropriate open source
+    license and I have the right under that license to submit that
+    work with modifications, whether created in whole or in part
+    by me, under the same open source license (unless I am
+    permitted to submit under a different license), as indicated
+    in the file; or
+
+(c) The contribution was provided directly to me by some other
+    person who certified (a), (b) or (c) and I have not modified
+    it.
+
+(d) I understand and agree that this project and the contribution
+    are public and that a record of the contribution (including all
+    personal information I submit with it, including my sign-off) is
+    maintained indefinitely and may be redistributed consistent with
+    this project or the open source license(s) involved.
+```
+
+## References
+
+* Overall CONTRIB adapted from https://github.com/mathjax/MathJax/blob/master/CONTRIBUTING.md
+* Conduct section adapted from the Contributor Covenant, version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html

LICENSE.txt → LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2018, Respective Authors all rights reserved.
+Copyright (c) 2017-2019 block.one and its contributors.  All rights reserved.
 
 The MIT License
 

README.md

@@ -1,22 +1,22 @@
-⚠️ ***Important! We recently released a major breaking rewrite for eosjs. Be sure to lock your dependencies.*** ⚠️
-
-If you are looking for the the previous version of `eosjs` you can [find it here](https://github.com/EOSIO/eosjs/tree/v16.0.9).
-
-# eosjs
+# eosjs ![npm](https://img.shields.io/npm/dw/eosjs.svg)
 
 Javascript API for integration with EOSIO-based blockchains using [EOSIO RPC API](https://developers.eos.io/eosio-nodeos/reference).
 
 Documentation can be found [here](https://eosio.github.io/eosjs)
 
 ## Installation
 
+### NPM
+
+The official distribution package can be found at [npm](https://www.npmjs.com/package/eosjs).
+
 ### NodeJS Dependency
 
-`npm install eosjs@beta` or `yarn add eosjs@beta`
+`yarn add eosjs`
 
 ### Browser Distribution
 
-Clone this repository locally then run `npm run build-web` or `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).
+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).
 
 ## Import
 
@@ -25,19 +25,18 @@ Clone this repository locally then run `npm run build-web` or `yarn build-web`.
 Importing using ES6 module syntax in the browser is supported if you have a transpiler, such as Babel.
 ```js
 import { Api, JsonRpc, RpcError } from 'eosjs';
-
-import JsSignatureProvider from 'eosjs/dist/eosjs-jssig'; // development only
+import { JsSignatureProvider } from 'eosjs/dist/eosjs-jssig';           // development only
 ```
 
 ### CommonJS
 
 Importing using commonJS syntax is supported by NodeJS out of the box.
 ```js
 const { Api, JsonRpc, RpcError } = require('eosjs');
-const JsSignatureProvider = require('eosjs/dist/eosjs-jssig');  // development only
-const fetch = require('node-fetch');                            // node only; not needed in browsers
-const { TextEncoder, TextDecoder } = require('util');           // node only; native TextEncoder/Decoder
-const { TextEncoder, TextDecoder } = require('text-encoding');  // React Native, IE11, and Edge Browsers only
+const { JsSignatureProvider } = require('eosjs/dist/eosjs-jssig');      // development only
+const fetch = require('node-fetch');                                    // node only; not needed in browsers
+const { TextEncoder, TextDecoder } = require('util');                   // node only; native TextEncoder/Decoder
+const { TextEncoder, TextDecoder } = require('text-encoding');          // React Native, IE11, and Edge Browsers only
 ```
 
 ## Basic Usage
@@ -49,7 +48,7 @@ The Signature Provider holds private keys and is responsible for signing transac
 ***Using the JsSignatureProvider in the browser is not secure and should only be used for development purposes. Use a secure vault outside of the context of the webpage to ensure security when signing transactions in production***
 
 ```js
-const defaultPrivateKey = "5JtUScZK2XEp3g9gh7F8bwtPTRAkASmNrrftmx4AxDKD5K4zDnr"; // useraaaaaaaa
+const defaultPrivateKey = "5JtUScZK2XEp3g9gh7F8bwtPTRAkASmNrrftmx4AxDKD5K4zDnr"; // bob
 const signatureProvider = new JsSignatureProvider([defaultPrivateKey]);
 ```
 
@@ -62,7 +61,7 @@ const rpc = new JsonRpc('http://127.0.0.1:8888', { fetch });
 
 ### API
 
-Include textDecoder and textEncoder when using in browser.
+Include textDecoder and textEncoder when using in Node, React Native, IE11 or Edge Browsers.
 ```js
 const api = new Api({ rpc, signatureProvider, textDecoder: new TextDecoder(), textEncoder: new TextEncoder() });
 ```
@@ -112,10 +111,16 @@ try {
 ...
 ```
 
-## Running Tests
+## Contributing
+
+[Contributing Guide](./CONTRIBUTING.md)
+
+[Code of Conduct](./CONTRIBUTING.md#conduct)
+
+## License
+
+[MIT](./LICENSE)
 
-### Automated Unit Test Suite
-`npm run test` or `yarn test`
+## Important
 
-### Web Integration Test Suite
-Run `npm run build-web` to build the browser distrubution then open `src/tests/web.html` in the browser of your choice.  The file should run through 6 tests, relaying the results onto the webpage with a 2 second delay after each test.  The final 2 tests should relay the exceptions being thrown onto the webpage for an invalid transaction and invalid rpc call.
+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.

cypress.json

@@ -0,0 +1,12 @@
+{
+  "video": true,
+  "fixturesFolder": false,
+  "pluginsFile": false,
+  "supportFile": false,
+  "reporter": "mochawesome",
+    "reporterOptions": {
+      "reportDir": "reports",
+      "overwrite": false
+    },
+  "userAgent": "Chrome cypress"
+}

cypress/integration/index.spec.js

@@ -0,0 +1,13 @@
+describe('eosjs web test', () => {
+  it('loads', () => {
+    cy.visit(('./src/tests/web.html'));
+  });
+  it('runs all tests successfully', () => {
+    cy.visit(('./src/tests/web.html'))
+    cy.get('div.tests>div>button').each((test) => { // iterate through all the tests
+      cy.wrap(test).click(); // click the button to start the test
+      cy.wrap(test).contains('Success', { timeout: 5000 });  // wait 5 seconds for success or treat as failure
+      cy.wait(500); // allow time for transaction to confirm (prevents duplicate transactions)
+    });
+  });
+})

docs/2.-Transaction-Examples.md

@@ -1,21 +1,37 @@
 # Transactions
 
-To be able to send transactions and trigger actions on the blockchain, you must have an instance of `Api`.
+To send transactions and trigger actions on the blockchain, you must have an instance of `Api`.
 
-The signature provider must contains the private keys corresponsing to the actors and permissions of the actions. 
+The signature provider must contain the private keys corresponding to the actors and permission requirements of the actions being executed.
+
+
+## CommonJS
 
 ```javascript
 const { Api, JsonRpc } = require('eosjs');
-const JsSignatureProvider = require('eosjs/dist/eosjs-jssig');  // development only
-const fetch = require('node-fetch');                            // node only; not needed in browsers
-const { TextDecoder, TextEncoder } = require('text-encoding');  // node, IE11 and IE Edge Browsers
+const { JsSignatureProvider } = require('eosjs/dist/eosjs-jssig');  // development only
+const fetch = require('node-fetch');                                // node only
+const { TextDecoder, TextEncoder } = require('util');               // node only
+const { TextEncoder, TextDecoder } = require('text-encoding');      // React Native, IE11, and Edge Browsers only
 
 const privateKeys = [privateKey1];
 
 const signatureProvider = new JsSignatureProvider(privateKeys);
 const rpc = new JsonRpc('http://127.0.0.1:8888', { fetch });
 const api = new Api({ rpc, signatureProvider, textDecoder: new TextDecoder(), textEncoder: new TextEncoder() });
+```
 
+## ES Modules
+
+```javascript
+import { Api, JsonRpc } from 'eosjs';
+import { JsSignatureProvider } from 'eosjs/dist/eosjs-jssig';  // development only
+
+const privateKeys = [privateKey1];
+
+const signatureProvider = new JsSignatureProvider(privateKeys);
+const rpc = new JsonRpc('http://127.0.0.1:8888');
+const api = new Api({ rpc, signatureProvider })
 ```
 
 ## Examples