feat(block): spec

API/block/README.md

@@ -1,2 +1,78 @@
 block API
 =========
+
+#### `get`
+
+> Get a raw IPFS block.
+
+##### `Go` **WIP**
+
+##### `JavaScript` - ipfs.block.get(multihash, [callback])
+
+`multihash` is a [multihash][] which can be passed as
+
+- Buffer, the raw Buffer of the multihash 
+- String, the base58 encoded version of the multihash
+
+`callback` must follow `function (err, block) {}` signature, where `err` is an error if the operation was not successful and `block` is a [Block][].
+
+
+```js
+ipfs.block.get(multihash, function (err, data) {
+  // data is the raw data contained in a block
+})
+```
+
+If no `callback` is passed, a promise is returned.
+
+
+
+
+#### `put`
+
+> Stores input as an IPFS block.
+
+##### `Go` **WIP**
+
+##### `JavaScript` - ipfs.block.put(data, [callback])
+
+Where `data` can be a
+
+- Buffer, requiring that the encoding is specified on the options. if no 
+  encoding is specified, Buffer is treated as the Data field
+- [Block][] instance
+
+`callback` has the signature `function (err, block) {}`, where `err` is an error
+if the operation was not successful. and `block` is a [Block][].
+
+If no `callback` is passed, a promise is returned.
+
+
+
+
+
+#### `stat`
+
+> Print information of a raw IPFS block.
+
+##### `Go` **WIP**
+
+##### `JavaScript` - ipfs.block.stat(multihash, [callback])
+
+`multihash` is a [multihash][] which can be passed as:
+
+- Buffer, the raw Buffer of the multihash (or of and encoded version)
+- String, the toString version of the multihash (or of an encoded version)
+
+`callback` must follow the signature `function (err, stats) {}`, where `err` is
+an error if the operation was not successful and `stats` is an object with
+the format
+
+```JavaScript
+{
+  Key: 'QmPTkMuuL6PD8L2SwTwbcs1NPg14U8mRzerB1ZrrBrkSDD',
+  Size: 10
+}
+```
+
+If no `callback` is passed, a promise is returned.

src/block.js

@@ -0,0 +1,87 @@
+/* eslint-env mocha */
+/* globals apiClients */
+'use strict'
+
+const expect = require('chai').expect
+
+module.exports = (common) => {
+  describe.only('.block', () => {
+    const blorbKey = 'QmPv52ekjS75L4JmHpXVeuJ5uX2ecSfSZo88NSyxwA3rAQ'
+    const blorb = Buffer('blorb')
+
+    it('returns an error when putting an array of files', () => {
+      return apiClients.a.block.put([blorb, blorb], (err) => {
+        console.log(err)
+        expect(err).to.be.an.instanceof(Error)
+      })
+    })
+
+    it('block.put', (done) => {
+      apiClients.a.block.put(blorb, (err, res) => {
+        expect(err).to.not.exist
+        expect(res).to.have.a.property('Key', 'QmPv52ekjS75L4JmHpXVeuJ5uX2ecSfSZo88NSyxwA3rAQ')
+        done()
+      })
+    })
+
+    it('block.get', (done) => {
+      apiClients.a.block.get(blorbKey, (err, res) => {
+        expect(err).to.not.exist
+
+        let buf = ''
+        res
+          .on('data', function (data) { buf += data })
+          .on('end', function () {
+            expect(buf).to.be.equal('blorb')
+            done()
+          })
+      })
+    })
+
+    it('block.stat', (done) => {
+      apiClients.a.block.stat(blorbKey, (err, res) => {
+        expect(err).to.not.exist
+        expect(res).to.have.property('Key')
+        expect(res).to.have.property('Size')
+        done()
+      })
+    })
+
+    describe('promise', () => {
+      it('returns an error when putting an array of files', () => {
+        return apiClients.a.block.put([blorb, blorb])
+          .catch((err) => {
+            expect(err).to.be.an.instanceof(Error)
+          })
+      })
+
+      it('block.put', () => {
+        return apiClients.a.block.put(blorb)
+          .then((res) => {
+            expect(res).to.have.a.property('Key', 'QmPv52ekjS75L4JmHpXVeuJ5uX2ecSfSZo88NSyxwA3rAQ')
+          })
+      })
+
+      it('block.get', (done) => {
+        return apiClients.a.block.get(blorbKey)
+          .then((res) => {
+            let buf = ''
+            res
+              .on('data', function (data) { buf += data })
+              .on('end', function () {
+                expect(buf).to.be.equal('blorb')
+                done()
+              })
+          })
+      })
+
+      it('block.stat', () => {
+        return apiClients.a.block.stat(blorbKey)
+          .then((res) => {
+            expect(res).to.have.property('Key')
+            expect(res).to.have.property('Size')
+          })
+      })
+    })
+  })
+}

src/index.js

@@ -6,3 +6,4 @@ exports.config = require('./config')
 exports.pin = require('./pin')
 exports.generic = require('./generic')
 exports.swarm = require('./swarm')
+exports.block = require('./block')