Merge pull request #11 from bigchaindb/feature/instructions

Streamline readme & onboarding

.babelrc

@@ -1,25 +1,25 @@
 {
-    'presets': ['es2015-no-commonjs'],
+    "presets": ["es2015-no-commonjs"],
-    'plugins': [
+    "plugins": [
-        'transform-export-extensions',
+        "transform-export-extensions",
-        'transform-object-assign',
+        "transform-object-assign",
-        'transform-object-rest-spread'
+        "transform-object-rest-spread"
     ],
-    'sourceMaps': true,
+    "sourceMaps": true,
 
-    'env': {
+    "env": {
-        'bundle': {
+        "bundle": {
-            'plugins': [
+            "plugins": [
-                ['transform-runtime', {
+                ["transform-runtime", {
-                    'polyfill': true,
+                    "polyfill": true,
-                    'regenerator': false
+                    "regenerator": false
                 }]
             ]
         },
-        'cjs': {
+        "cjs": {
-            'plugins': [
+            "plugins": [
-                'add-module-exports',
+                "add-module-exports",
-                'transform-es2015-modules-commonjs'
+                "transform-es2015-modules-commonjs"
             ]
         }
     }

.eslintignore

@@ -1,3 +1,5 @@
 build/*
 dist/*
 node_modules/*
+yarn.lock
+package-lock.json

.travis.yml

@@ -0,0 +1,15 @@
+language: node_js
+node_js: node
+
+install: npm install
+
+script:
+  - npm run clean
+  - npm run build
+
+cache:
+  directories:
+    - node_modules
+  
+notifications:
+    email: false

AUTHORS.rst

@@ -1,13 +0,0 @@
-=======
-Credits
-=======
-
-Development Lead
-----------------
-
-* BigchainDB <dev@bigchaindb.com>
-
-Contributors
-------------
-
-Inspired by @Sohkai. Why not be the second?

CHANGELOG.rst

@@ -1,7 +0,0 @@
-Changelog
-=========
-
-0.0.1a1 (2017-05-09)
---------------------
-
-* Planning release on npm.

LICENSE

@@ -0,0 +1,174 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+that You distribute, all copyright, patent, trademark, and
+attribution notices from the Source form of the Work,
+excluding those notices that do not pertain to any part of
+the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained
+within such NOTICE file, excluding those notices that do not
+pertain to any part of the Derivative Works, in at least one
+of the following places: within a NOTICE text file distributed
+as part of the Derivative Works; within the Source form or
+documentation, if provided along with the Derivative Works; or,
+within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and
+do not modify the License. You may add Your own attribution
+notices within Derivative Works that You distribute, alongside
+or as an addendum to the NOTICE text from the Work, provided
+that such additional attribution notices cannot be construed
+as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.

LICENSES.md

@@ -1,9 +0,0 @@
-# Code Licenses
-
-All code in _this_ repository (including short code snippets embedded in the official BigchainDB _documentation_) is licensed under the Apache Software License 2.0, the full text of which can be found at [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0).
-
-For the licenses on all other BigchainDB-related code, see the license file in the associated repository.
-
-# Documentation Licenses
-
-The official BigchainDB documentation, _except for the short code snippets embedded within it_, is licensed under a Creative Commons Attribution-ShareAlike 4.0 International license, the full text of which can be found at [http://creativecommons.org/licenses/by-sa/4.0/legalcode](http://creativecommons.org/licenses/by-sa/4.0/legalcode).

README.md

@@ -1,67 +1,51 @@
-# JavaScript Driver for BigchainDB
+# [![js-bigchaindb-driver](media/repo-banner@2x.png)](https://www.bigchaindb.com)
 
-> Inspired by [`js-bigchaindb-quickstart`](https://github.com/sohkai/js-bigchaindb-quickstart) of @sohkhai [thanks]
+> Official JavaScript driver for [BigchainDB](https://github.com/bigchaindb/bigchaindb) with some naive helpers to get you on your way making transactions in Node.js and the browser.
 
-> Supports BigchainDB Server v0.10 (Warning: use CORS enabled [branch](https://github.com/bigchaindb/bigchaindb/tree/kyber-master-feat-cors) untill [PR #1311](https://github.com/bigchaindb/bigchaindb/pull/1311) is resolved )
+[![npm](https://img.shields.io/npm/v/js-bigchaindb-driver.svg)](https://www.npmjs.com/package/js-bigchaindb-driver)
-
+[![js bigchaindb](https://img.shields.io/badge/js-bigchaindb-39BA91.svg)](https://github.com/ascribe/javascript)
-Some naive helpers to get you on your way to making some transactions, if you'd like to use
+[![Build Status](https://travis-ci.org/bigchaindb/js-bigchaindb-driver.svg?branch=master)](https://travis-ci.org/bigchaindb/js-bigchaindb-driver)
-[BigchainDB](https://github.com/bigchaindb/bigchaindb) with JavaScript.
+[![Greenkeeper badge](https://badges.greenkeeper.io/bigchaindb/js-bigchaindb-driver.svg)](https://greenkeeper.io/)
-
-Aimed to support usage in browsers or node and ES∞+, so
-you'll probably need a babel here and a bundler there (or use [one of the built versions](./dist)),
-of which I expect you'll know quite well ([otherwise, go check out js-reactor](https://github.com/bigchaindb/js-reactor)).
 
 ## Compatibility
 
-| BigchainDB Server | BigchainDB Javascript Driver |
+| BigchainDB Server | BigchainDB JavaScript Driver |
 | ----------------- |------------------------------|
 | `~=0.10.1` | `~=0.1.0` |
 
 
 ## Contents
 
-- [Getting Started](#getting-started)
+- [Installation](#installation)
 - [Usage](#usage)
 - [Speed Optimizations](#speed-optimizations)
 - [Warnings](#warnings)
-- [API](API.md)
+- [npm releases](#npm-releases)
+- [Authors](#authors)
+- [License](#license)
+- [API reference](API.md)
 
-## Getting started
+## Installation
-
-### Install from npm
 
 ```bash
 # install from npm
-npm install js-bigchaindb-driver
+npm install bigchaindb-driver
-# Install from GitHub - ssh
-npm install git+ssh://github.com/bigchaindb/js-bigchaindb-driver.git
-# Install from GitHub - https
-npm install git+https://github.com/bigchaindb/js-bigchaindb-driver.git
-```
-
-### Import / ES6
-
-```javascript
-// ES6 Browser
-import * as driver from 'js-bigchaindb-driver';
-// ES<<6 Browser
-let driver = require('js-bigchaindb-driver');
-// ES<<6 CommonJS / node
-let driver = require('js-bigchaindb-driver/dist/node');
 ```
 
 ## Usage
 
-```javascript
+You'll probably need a babel here and a bundler there. Alternatively, use [one of the bundled dist versions](./dist).
+
+```js
 import * as driver from 'js-bigchaindb-driver';
 
 // http(s)://<bigchaindb-API-url>/ (e.g. http://localhost:9984/api/v1/)
 const API_PATH = 'http://localhost:9984/api/v1/';
 
-// create a new user with a public-private keypair
+// Create a new user with a public-private key pair
 const alice = new driver.Ed25519Keypair();
 
-// Create a transation
+// Create a transaction
 const tx = driver.Transaction.makeCreateTransaction(
     { assetMessage: 'My very own asset...' },
     { metaDataMessage: 'wrapped in a transaction' },
@@ -71,10 +55,10 @@ const tx = driver.Transaction.makeCreateTransaction(
     alice.publicKey
 );
 
-// sign/fulfill the transaction
+// Sign/fulfill the transaction
 const txSigned = driver.Transaction.signTransaction(tx, alice.privateKey);
 
-// send it off to BigchainDB
+// Send it off to BigchainDB
 let conn = new driver.Connection(PATH, { 'Content-Type': 'application/json' });
 conn.postTransaction(txSigned)
     .then(() => conn.getStatus(txSigned.id))
@@ -85,39 +69,28 @@ You may also be interested in some [long-form tutorials with actual code](https:
 
 The expected flow for making transactions:
 
-1. Go get yourself some keypairs! (or a whole bunch of them, nobody's
+1. Go get yourself some key pairs. (or a whole bunch of them, nobody's counting)
-   counting)
     - `new driver.Ed25519Keypair()` 
-1. Construct a transaction payload that you can send of to BigchainDB:
+2. Construct a transaction payload that you can send off to BigchainDB:
     - `driver.Transaction.makeCreateTransaction()` for creating a new asset or
-    - `driver.Transaction.makeTransferTransaction()` for transfering an existing asset
+    - `driver.Transaction.makeTransferTransaction()` for transferring an existing asset
-1. A transaction needs an output (\*):
+3. A transaction needs an output (\*):
     - `driver.Transaction.makeOutput()` still requires a crypto-condition
     - `driver.Transaction.makeEd25519Condition()` should do the trick for a simple public key output.
-1. (**Optional**) You've got everything you need, except for an asset and metadata. Maybe define them (any
+4. (**Optional**) You've got everything you need, except for an asset and metadata. Maybe define them (any JSON-serializable object will do).
-   JSON-serializable object will do).
+5. Ok, now you've got a transaction, but we need you to *sign* it cause, you know... cryptography and `¯\_(ツ)_/¯`:
-1. Ok, now you've got a transaction, but we need you to *sign* it cause, you
-   know... cryptography and `¯\_(ツ)_/¯`:
    - `driver.Transaction.signTransaction()` allows you to sign with private keys.
-1. Final step is to send the transaction off to BigchainDB:
+6. Final step is to send the transaction off to BigchainDB:
    - `driver.Connection.postTransaction()`
 
-
+(\*) If you're not sure what any of this means (and you're as confused as I think you are right now), you might wanna go check out [this](https://docs.bigchaindb.com/projects/server/en/latest/data-models/crypto-conditions.html) and [this](https://docs.bigchaindb.com/projects/py-driver/en/latest/usage.html#asset-transfer) and [this](https://tools.ietf.org/html/draft-thomas-crypto-conditions-01) first.
-(\*) If you're not sure what any of this means (and you're as
-   confused as I think you are right now), you might wanna go check out [this](https://docs.bigchaindb.com/projects/server/en/latest/data-models/crypto-conditions.html)
-   and [this](https://docs.bigchaindb.com/projects/py-driver/en/latest/usage.html#asset-transfer)
-   and [this](https://tools.ietf.org/html/draft-thomas-crypto-conditions-01) first.
 
 ## Speed Optimizations
 
-This implementation plays "safe" by using JS-native (or downgradable) libraries for its
+This implementation plays "safe" by using JS-native (or downgradable) libraries for its crypto-related functions to keep compatibilities with the browser. If you do want some more speed, feel free to explore the following: 
-crypto-related functions to keep compatibilities with the browser. If you do want some more speed, feel free to explore the following: 
 
-* [chloride](https://github.com/dominictarr/chloride), or its underlying [sodium](https://github.com/paixaop/node-sodium)
+* [chloride](https://github.com/dominictarr/chloride), or its underlying [sodium](https://github.com/paixaop/node-sodium) library
-  library
+* [node-sha3](https://github.com/phusion/node-sha3) -- **MAKE SURE** to use [steakknife's fork](https://github.com/steakknife/node-sha3) if [the FIPS 202 upgrade](https://github.com/phusion/node-sha3/pull/25) hasn't been merged (otherwise, you'll run into all kinds of hashing problems)
-* [node-sha3](https://github.com/phusion/node-sha3) -- **MAKE SURE** to use [steakknife's fork](https://github.com/steakknife/node-sha3)
-  if [the FIPS 202 upgrade](https://github.com/phusion/node-sha3/pull/25) hasn't been merged
-  (otherwise, you'll run into all kinds of hashing problems)
 
 ## Warnings
 
@@ -125,24 +98,72 @@ crypto-related functions to keep compatibilities with the browser. If you do wan
 
 Make sure you keep using a crypto-conditions implementation that implements the older v1 draft (e.g.
 [`five-bells-condition@v3.3.1`](https://github.com/interledgerjs/five-bells-condition/releases/tag/v3.3.1)).
-BigchainDB Server 0.10 does not implement the newer version of the spec and **WILL** fail if you to
+
-use a newer implementation of crypto-conditions.
+BigchainDB Server 0.10 does not implement the newer version of the spec and **WILL** fail if you try using a newer implementation of crypto-conditions.
 
 > SHA3
 
-Make sure to use a SHA3 implementation that has been upgraded as per [FIPS 202](http://csrc.nist.gov/publications/drafts/fips-202/fips_202_draft.pdf).
+Make sure to use a SHA3 implementation that has been upgraded as per [FIPS 202](http://csrc.nist.gov/publications/drafts/fips-202/fips_202_draft.pdf). Otherwise, the hashes you generate **WILL** be invalid in the eyes of the BigchainDB Server.
-Otherwise, the hashes you generate **WILL** be invalid in the eyes of the BigchainDB Server.
 
 > Ed25519
 
-If you do end up replacing `tweetnacl` with `chloride` (or any other `Ed25519` package), you might
+If you do end up replacing `tweetnacl` with `chloride` (or any other `Ed25519` package), you might want to double check that it gives you a correct public/private (or verifying/signing, if they use
-want to double check that it gives you a correct public/private (or verifying/signing, if they use
+that lingo) key pair.
-that lingo) keypair.
 
-An example BigchainDB Server-generated keypair (encoded in `base58`):
+An example BigchainDB Server-generated key pair (encoded in `base58`):
 
 - Public: `DjPMHDD9JtgypDKY38mPz9f6owjAMAKhLuN1JfRAat8C`
 - Private: `7Gf5YRch2hYTyeLxqNLgTY63D9K5QH2UQ7LYFeBGuKvo`
 
-Your package should be able to take in the decoded version of the **private** key and return you the
+Your package should be able to take in the decoded version of the **private** key and return you the same **public** key (once you encode that to `base58`).
-same **public** key (once you encode that to `base58`).
+
+## npm releases
+
+For a new **patch release**, execute on the machine where you're logged into your npm account:
+
+```bash
+npm run release
+```
+
+Command is powered by [`release-it`](https://github.com/webpro/release-it) package, defined in the `package.json`.
+
+That's what the command does without any user interaction:
+
+- create release commit by updating version in `package.json`
+- create tag for that release commit
+- push commit & tag
+- create a new release on GitHub, with change log auto-generated from commit messages
+- publish to npm as a new release
+
+If you want to create a **minor** or **major release**, use these commands:
+
+```bash
+npm run release-minor
+```
+
+```bash
+npm run release-major
+```
+
+## Authors
+
+* inspired by [`js-bigchaindb-quickstart`](https://github.com/sohkai/js-bigchaindb-quickstart) of @sohkhai [thanks]
+* BigchainDB <dev@bigchaindb.com>
+
+## License
+
+```
+Copyright 2017 BigchainDB GmbH
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+```

package.json

@@ -1,14 +1,14 @@
 {
-  "name": "js-bigchaindb-driver",
+  "name": "bigchaindb-driver",
   "version": "0.1.1",
-  "description": "JavaScript driver for BigchainDB (node + browser)",
+  "description": "Node.js driver for BigchainDB",
   "homepage": "https://www.bigchaindb.com/",
   "bugs": "https://github.com/bigchaindb/js-bigchaindb-driver/issues",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/bigchaindb/js-bigchaindb-driver.git"
   },
-  "license": "Apache Software License 2.0",
+  "license": "Apache-2.0",
   "author": "BigchainDB",
   "main": "./dist/bundle/bundle.js",
   "scripts": {
@@ -18,7 +18,10 @@
     "build:cjs": "cross-env BABEL_ENV=cjs babel ./src -d dist/node",
     "build:dist": "cross-env NODE_ENV=production webpack -p",
     "clean": "rimraf dist/bundle dist/node",
-    "test": "echo \"Error: no test specified AWWWW YEAHHH\" && exit 1"
+    "test": "echo \"Error: no test specified AWWWW YEAHHH\" && exit 1",
+    "release": "./node_modules/release-it/bin/release.js --src.tagName='v%s' --github.release --npm.publish --non-interactive",
+    "release-minor": "./node_modules/release-it/bin/release.js minor --src.tagName='v%s' --github.release --npm.publish --non-interactive",
+    "release-major": "./node_modules/release-it/bin/release.js major --src.tagName='v%s' --github.release --npm.publish --non-interactive"
   },
   "devDependencies": {
     "babel-cli": "^6.22.2",
@@ -37,6 +40,7 @@
     "eslint": "^3.14.1",
     "eslint-config-ascribe": "^3.0.1",
     "eslint-plugin-import": "^2.2.0",
+    "release-it": "^2.7.3",
     "rimraf": "^2.5.4",
     "webpack": "^2.2.1"
   },
@@ -48,7 +52,7 @@
     "decamelize": "^1.2.0",
     "es6-promise": "^4.0.5",
     "fetch-ponyfill": "^4.0.0",
-    "five-bells-condition": "=3.3.1",
+    "five-bells-condition": "3.3.1",
     "isomorphic-fetch": "^2.2.1",
     "js-sha3": "^0.5.7",
     "js-utility-belt": "^1.5.0",