Merge pull request #305 from ipfs/ipfs-api/ng

next generation

Author: daviddias

.travis.yml

@@ -11,7 +11,7 @@ before_install:
 
 script:
   - npm run lint
-  - npm test
+  - npm run test:node
   - npm run coverage
 
 addons:

API.md

@@ -1,4 +1,5 @@
-# js-ipfs-api
+ipfs-api
+========
 
 [![](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square)](http://ipn.io)
 [![](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](http://ipfs.io/)
@@ -9,7 +10,9 @@
 [![Travis CI](https://travis-ci.org/ipfs/js-ipfs-api.svg?branch=master)](https://travis-ci.org/ipfs/js-ipfs-api)
 [![Circle CI](https://circleci.com/gh/ipfs/js-ipfs-api.svg?style=svg)](https://circleci.com/gh/ipfs/js-ipfs-api)
 
-> A client library for the IPFS HTTP API, implemented in JavaScript.
+> A client library for the IPFS HTTP API, implemented in JavaScript. This client library implements the [interface-ipfs-core](https://github.com/ipfs/interface-ipfs-core) enabling applications to change between a embebed js-ipfs node and any remote IPFS node without having to change the code. In addition, this client library implements a set of utility functions.
+
+![](https://github.com/ipfs/interface-ipfs-core/raw/master/img/badge.png)
 
 ## Table of Contents
 
@@ -102,16 +105,71 @@ $ ipfs config --json API.HTTPHeaders.Access-Control-Allow-Origin "[\"http://exam
 
 ### API
 
-> `WIP`
-
-`js-ipfs-api` follows the spec defined by [`interface-ipfs-core`](https://github.com/ipfs/interface-ipfs-core), which concerns the interface to expect from IPFS implementations. This interface is a currently active endeavor - expect it to be complete in the next few weeks (August 2016). You can use it today to consult the methods available.
+> `js-ipfs-api` follows the spec defined by [`interface-ipfs-core`](https://github.com/ipfs/interface-ipfs-core), which concerns the interface to expect from IPFS implementations. This interface is a currently active endeavor - expect it to be complete in the next few weeks (August 2016). You can use it today to consult the methods available.
 
-### Extra API methods
+### Utility functions
 
-Adding to the methods defined by [`interface-ipfs-core`](https://github.com/ipfs/interface-ipfs-core), `js-ipfs-api` exposes a set of extra utility methods.
+Adding to the methods defined by [`interface-ipfs-core`](https://github.com/ipfs/interface-ipfs-core), `js-ipfs-api` exposes a set of extra utility methods. These utility functions are scoped behind the `ipfs.util`.
 
 Complete documentation for these methods is coming with: https://github.com/ipfs/js-ipfs-api/pull/305
 
+
+#### Add files or entire directories from the FileSystem to IPFS
+
+> `ipfs.util.addFromFs(path, option, callback)`
+
+Reads a file from `path` on the filesystem  and adds it to IPFS. If `path` is a directory, use option `{ recursive: true }` to add the directory and all its sub-directories.
+
+```JavaScript
+ipfs.util.addFromFs('path/to/a/file', { recursive: true }, (err, result) => {
+  if (err) {
+    throw err
+  }
+  console.log(result)
+})
+```
+
+`result` is an array of objects describing the files that were added, such as:
+
+```
+[{
+  path: 'test-folder',
+  hash: 'QmRNjDeKStKGTQXnJ2NFqeQ9oW23WcpbmvCVrpDHgDg3T6',
+  size: 2278
+},
+// ...
+]
+```
+
+#### Add a file from a URL to IPFS
+
+> `ipfs.util.addFromURL(url, callback)`
+
+```JavaScript
+ipfs.util.addFromURL('http://example.com/', (err, result) => {
+  if (err) {
+    throw err
+  }
+  console.log(result)
+})
+
+```
+
+#### Add a file from a stream to IPFS
+
+> `ipfs.util.addFromStream(stream, callback)`
+
+This is very similar to `ipfs.files.add({path:'', content: stream})`. It is like the reverse of cat
+
+```JavaScript
+ipfs.util.addFromStream(<readable-stream>, (err, result) => {
+  if (err) {
+    throw err
+  }
+  console.log(result)
+})
+```
+
 ### Callbacks and promises
 
 If you do not pass in a callback all API functions will return a `Promise`. For example:
@@ -135,9 +193,11 @@ yet available you need to bring your own polyfill.
 
 We run tests by executing `npm test` in a terminal window. This will run both Node.js and Browser tests, both in Chrome and PhantomJS. To ensure that the module conforms with the [`interface-ipfs-core`](https://github.com/ipfs/interface-ipfs-core) spec, we run the batch of tests provided by the interface module, which can be found [here](https://github.com/ipfs/interface-ipfs-core/tree/master/src).
 
+
+
 ## Contribute
 
-The js-ipfs API is a work in progress. As such, there's a few things you can do right now to help out:
+The js-ipfs-api is a work in progress. As such, there's a few things you can do right now to help out:
 
 * **[Check out the existing issues](https://github.com/ipfs/js-ipfs-api/issues)**!
 * **Perform code reviews**. More eyes will help a) speed the project along b) ensure quality and c) reduce possible future bugs.
@@ -148,6 +208,10 @@ The js-ipfs API is a work in progress. As such, there's a few things you can do
 
 [![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/contributing.md)
 
+## Historical context
+
+This module started as a direct mapping from the go-ipfs cli to a JavaScript implementation, although this was useful and familiar to a lot of developers that were coming to IPFS for the first time, it also created some confusion on how to operate the core of IPFS and have access to the full capacity of the protocol. After much consideration, we decided to create `interface-ipfs-core` with the goal of standardizing the interface of a core implementation of IPFS, and keep the utility functions the IPFS community learned to use and love, such as reading files from disk and storing them directly to IPFS.
+
 ## License
 
 [MIT](LICENSE)

README.md

@@ -1,9 +1,21 @@
 {
   "name": "ipfs-api",
   "version": "6.0.3",
-  "description": "A client library for the IPFS API",
+  "description": "A client library for the IPFS HTTP API. Follows interface-ipfs-core spec",
   "main": "lib/index.js",
   "jsnext:main": "src/index.js",
+  "scripts": {
+    "test": "node --max_old_space_size=4096 node_modules/.bin/gulp test:node",
+    "test:node": "gulp test:node",
+    "test:browser": "node --max_old_space_size=4096 node_modules/.bin/gulp test:browser",
+    "lint": "aegir-lint",
+    "build": "gulp build",
+    "release": "node --max_old_space_size=4096 node_modules/.bin/gulp release",
+    "release-minor": "node --max_old_space_size=4096 node_modules/.bin/gulp release --type minor",
+    "release-major": "node --max_old_space_size=4096 node_modules/.bin/gulp release --type major",
+    "coverage": "gulp coverage",
+    "coverage-publish": "aegir-coverage publish"
+  },
   "dependencies": {
     "async": "^2.0.1",
     "babel-runtime": "^6.11.6",
@@ -20,6 +32,7 @@
     "ndjson": "^1.4.3",
     "promisify-es6": "^1.0.1",
     "qs": "^6.2.1",
+    "tar-stream": "^1.5.2",
     "wreck": "^9.0.0"
   },
   "engines": {
@@ -30,32 +43,19 @@
     "url": "https://github.com/ipfs/js-ipfs-api"
   },
   "devDependencies": {
-    "aegir": "^6.0.0",
+    "aegir": "^6.0.1",
     "chai": "^3.5.0",
     "gulp": "^3.9.1",
     "hapi": "^14.1.0",
-    "interface-ipfs-core": "^0.8.0",
+    "interface-ipfs-core": "^0.13.0",
     "ipfsd-ctl": "^0.14.0",
-    "passthrough-counter": "^1.0.0",
     "pre-commit": "^1.1.3",
     "socket.io": "^1.4.8",
     "socket.io-client": "^1.4.8",
     "stream-equal": "^0.1.8",
     "stream-http": "^2.3.1",
     "streamifier": "^0.1.1"
   },
-  "scripts": {
-    "test": "gulp test",
-    "test:node": "gulp test:node",
-    "test:browser": "gulp test:browser",
-    "lint": "aegir-lint",
-    "build": "gulp build",
-    "release": "gulp release",
-    "release-minor": "gulp release --type minor",
-    "release-major": "gulp release --type major",
-    "coverage": "gulp coverage",
-    "coverage-publish": "aegir-coverage publish"
-  },
   "pre-commit": [
     "lint",
     "test"