From fa879a85327280c018b7d01ad6ecca5feae7ce63 Mon Sep 17 00:00:00 2001 From: chris Date: Sun, 17 Dec 2017 13:22:24 -0500 Subject: [PATCH] added jsdoc for readme creation, supporting template, and npm scripts --- jsdoc2md/README.hbs | 563 ++++++++++++++++++++++++++++++++++++++++++++ package.json | 5 +- 2 files changed, 567 insertions(+), 1 deletion(-) create mode 100644 jsdoc2md/README.hbs diff --git a/jsdoc2md/README.hbs b/jsdoc2md/README.hbs new file mode 100644 index 0000000..cd03c27 --- /dev/null +++ b/jsdoc2md/README.hbs @@ -0,0 +1,563 @@ +!Important! Note +---- + +This is a maintained fork of the original package. **The npm package name has +changed** because we could not get access to the npmjs repository to keep it +updated. Please see the [Quick start](https://github.com/dparlevliet/node.bittrex.api#quick-start) section for the new package name and +instructions. + +Also, the **websocket code has changed** after Bittrex switched to using Cloudflare +so please see the new ``Websockets`` documentation and updated unit tests and +examples in the ``examples/`` folder. + + +Node Bittrex API +========= + +Node Bittrex API is an asynchronous node.js library for the Bittrex API - https://bittrex.com/. +The Bittrex API data can be received either as a GET request or via Websockets API. + +Documentation for the Bittrex API: https://bittrex.com/Home/Api + +This Library is licensed under the [MIT license](https://github.com/dparlevliet/node.bittrex.api/blob/master/LICENSE). + + +Contributors +---- +Thanks go to the people who have contributed code to this Library. + +* [n0mad01](https://github.com/n0mad01) Special kudos - the original creator of the library. Thanks for the hard work. +* [cyberwlf](https://github.com/armandohg) & [armandohg](https://github.com/armandohg) - Special thanks to them for the cloudflare websocket research and fix but also thanks to everyone else in [issue #67](https://github.com/n0mad01/node.bittrex.api/issues/67) +* [samuelhei](https://github.com/samuelhei) Special kudos - thanks to him all missing calls are complemented as also structural improvements have been made. +* [mhuggins](https://github.com/mhuggins) +* [192-sean](https://github.com/192-sean) +* [caffeinewriter](https://github.com/caffeinewriter) +* [apense](https://github.com/apense) +* [TheRealest](https://github.com/TheRealest) +* [Alexsey](https://github.com/Alexsey) + + +Before you start +---- +This is just a quick reminder that you are handling coins with this library (and thus real money), so, understand the situation as much as possible and make everything to prevent losing them. + +Here is a small checklist you should go through before you start: + +- Make sure you don't give your api key more rights as absolutely necessary - for first testing READ INFO alone should be enough! (bittrex.com under: Settings/API Keys) + +![bittrex_ap_keys_control](https://user-images.githubusercontent.com/260321/29748739-a6c2c00e-8b1c-11e7-95ec-1b0221348235.png) + +- make sure to understand the API Key permissions + 1. READ INFO - Allows you to read private details such as open orders, order history, balances, etc + 2. TRADE LIMIT - Allows you to create/cancel trade limit buy/sell orders + 3. TRADE MARKET - allows you to create/cancel market buy/sell orders + 4. WITHDRAW - Allows you to withdraw to another address +- Make use of the Bittrex IP Whitelist as also the Withdrawal Whitelist features +- Do not ever commit your API Keys to GitHub or expose them under any circumstances! + + +Quick start +---- +```sh +$ npm install node-bittrex-api +``` + +```javascript +var bittrex = require('node-bittrex-api'); +bittrex.options({ + 'apikey' : API_KEY, + 'apisecret' : API_SECRET, +}); +bittrex.getmarketsummaries( function( data, err ) { + if (err) { + return console.error(err); + } + for( var i in data.result ) { + bittrex.getticker( { market : data.result[i].MarketName }, function( ticker ) { + console.log( ticker ); + }); + } +}); +``` + + +Advanced start +---- + +fetch the project via git: +```sh +$ git clone https://github.com/dparlevliet/node.bittrex.api.git +``` + +then meet the package dependencies: +```sh +$ cd node.bittrex.api/ +$ npm install +``` + +Include ``node.bittrex.api.js`` into your project: +```javascript +var bittrex = require('./node.bittrex.api.js'); +``` + +##### Configuration +```javascript +bittrex.options({ + 'apikey' : API_KEY, + 'apisecret' : API_SECRET, + 'verbose' : true, + 'cleartext' : false +}); +``` + +By default the returned data is an object, in order to get clear text you have to add the option **cleartext** (streams will always return text): +```javascript +'cleartext' : true +``` + +The baseUrl itself can also be set via options +```javascript +'baseUrl' : 'https://bittrex.com/api/v1', +'baseUrlv2' : 'https://bittrex.com/Api/v2.0', +``` + +Change the callbacks arguments sequence +```javascript +'inverse_callback_arguments' : true, +``` +This simply changes the sequence in which the arguments are passed, instead of e.g.: +```javascript +getmarkethistory({market : 'USDT-BTC'}, function(data, error) {}); +``` +you'll get the reversed order: +```javascript +getmarkethistory({market : 'USDT-BTC'}, function(error, data) {}); +``` + + +Websockets +-- + +#### Basic example +```javascript +bittrex.websockets.client(function() { + console.log('Websocket connected'); + bittrex.websockets.subscribe(['BTC-ETH'], function(data) { + if (data.M === 'updateExchangeState') { + data.A.forEach(function(data_for) { + console.log('Market Update for '+ data_for.MarketName, data_for); + }); + } + }); +}); +``` + +#### Basic example with event emitters +```javascript +bittrex.options({ + websockets: { + onConnect: function() { + console.log('Websocket connected'); + bittrex.websockets.subscribe(['BTC-ETH'], function(data) { + if (data.M === 'updateExchangeState') { + data.A.forEach(function(data_for) { + console.log('Market Update for '+ data_for.MarketName, data_for); + }); + } + }); + }, + onDisconnect: function() { + console.log('Websocket disconnected'); + } + } +}); + +var websocketClient; +bittrex.websockets.client(function(client) { + websocketClient = client; +}); +``` + + +#### Available methods +All of these methods will build a websocket client and attempt a connection if +you have not run ``websockets.client`` yourself. See ``examples/`` for a better +understanding. + + +#### websockets.listen +This will subscribe to just the global ticker updates. + +```javascript +bittrex.websockets.listen(function(data, client) { + if (data.M === 'updateSummaryState') { + data.A.forEach(function(data_for) { + data_for.Deltas.forEach(function(marketsDelta) { + console.log('Ticker Update for '+ marketsDelta.MarketName, marketsDelta); + }); + }); + } +}); +``` + + +#### websockets.subscribe +This will subscribe to the specified markets data. To build +your candle data, order book and market history, etc. you will need to subscribe +to the individual markets you wish to watch. You can subscribe to all of them. + +```javascript +bittrex.websockets.subscribe(['BTC-ETH','BTC-SC','BTC-ZEN'], function(data, client) { + if (data.M === 'updateExchangeState') { + data.A.forEach(function(data_for) { + console.log('Market Update for '+ data_for.MarketName, data_for); + }); + } +}); +``` + + +#### Websocket serviceHandlers example +You can override the libraries logic for the following events. Note, this will +replace the libraries logic. +```javascript +websocketClient.serviceHandlers.reconnecting = function (message) { + return true; // set to true stops reconnect/retrying +} + +websocketClient.serviceHandlers.messageReceived = function (message) { + console.log(message); // the messages received must be parsed as json first e.g. via jsonic(message.utf8Data) +} +``` + +all possible serviceHandlers +```javascript +bound: function() { console.log("Websocket bound"); }, +connectFailed: function(error) { console.log("Websocket connectFailed: ", error); }, +connected: function(connection) { console.log("Websocket connected"); }, +disconnected: function() { console.log("Websocket disconnected"); }, +onerror: function (error) { console.log("Websocket onerror: ", error); }, +messageReceived: function (message) { console.log("Websocket messageReceived: ", message); return false; }, +bindingError: function (error) { console.log("Websocket bindingError: ", error); }, +connectionLost: function (error) { console.log("Connection Lost: ", error); }, +reconnecting: function (retry { inital: true/false, count: 0} ) { + console.log("Websocket Retrying: ", retry); + //return retry.count >= 3; // cancel retry true + return true; +} +``` + + +Streams +-- +Streams have been removed + + + +Examples +-- +After configuration you can use the object right away: +example #1 +```javascript +bittrex.getmarketsummaries( function( data, err ) { + if (err) { + return console.error(err); + } + for( var i in data.result ) { + bittrex.getticker( { market : data.result[i].MarketName }, function( ticker ) { + console.log( ticker ); + }); + } +}); +``` + +example #2 +```javascript +bittrex.getbalance({ currency : 'BTC' }, function( data, err ) { + if (err) { + return console.error(err); + } + console.log( data ); +}); +``` + + +Libraries +-- + +Websockets depends on the following npm packages: +- signalR websockets client https://www.npmjs.com/package/signalrjs +- jsonic JSON parser https://www.npmjs.com/package/jsonic +- cloudscraper https://www.npmjs.com/package/cloudscraper + + +Other libraries utilized: +- request https://www.npmjs.org/package/request + +For HmacSHA512 this package is using a part of Googles Crypto.js (the node crypt package could not provide any appropriate result). +- http://crypto-js.googlecode.com/svn/tags/3.1.2/build/rollups/hmac-sha512.js + + +Error examples +--- + +Example of request/domain based errors (not Bittrex API error) +```javascript +var url = 'http://fake.bittrex.com/api/v1.1/public/getticker?market=USDT-BTCXXX'; +bittrex.sendCustomRequest( url, function( data, err ) { + if (err) { + /** + { + success: false, + message: 'URL request error', + error: + { Error: getaddrinfo ENOTFOUND fake.bittrex.com fake.bittrex.com:80 + at errnoException (dns.js:28:10) + at GetAddrInfoReqWrap.onlookup [as oncomplete] (dns.js:76:26) + code: 'ENOTFOUND', + errno: 'ENOTFOUND', + syscall: 'getaddrinfo', + hostname: 'fake.bittrex.com', + host: 'fake.bittrex.com', + port: 80 }, + result: undefined + } + */ + return console.error(err); + } + console.log(data); +}); +``` + +Example of request/url based errors (not Bittrex API error) +```javascript +var url = 'http://bittrex.com/api/v1.1/public/getfakeendpoint'; +bittrex.sendCustomRequest( url, function( data, err ) { + if (err) { + /** + { + success: false, + message: 'URL request error', + error: undefined, + result: { + statusCode: 404, + statusMessage: 'Not Found', + body: '\r\n ...' + } + } + */ + return console.error(err); + } + console.log(data); +}); +``` + +Example of Bittrex API error +```javascript +bittrex.getcandles({ + marketName: 'USDT-BTC', + tickInterval: 300 +}, function(data, err) { + if (err) { + /** + { + success: false, + message: 'INVALID_TICK_INTERVAL', + result: null + } + */ + return console.error(err); + } + console.log(data); +}); +``` + + +Methods +---- + +Optional parameters may have to be looked up at https://bittrex.com/Home/Api. + +> It may happen that some Bittrex API methods are missing, also they could have been forgotten in the documentation. In this case, if this strikes you, feel free to open a issue or send me a pull request. + +> Also: the method **sendCustomRequest** enables completely custom requests, regardless the specific API methods. + +##### sendCustomRequest +- url String +- callback Function +- credentials Boolean optional whether the credentials should be applied to the request/stream or not, default is set to false. + +example #1 +```javascript +var url = 'https://bittrex.com/api/v1.1/public/getticker?market=BTC-LTC'; +bittrex.sendCustomRequest( url, function( data, err ) { + console.log( data ); +}); +``` + +example #2 (credentials applied to request/stream) +```javascript +bittrex.sendCustomRequest( 'https://bittrex.com/api/v1.1/account/getbalances?currency=BTC', function( data, err ) { + console.log( data ); +}, true ); + +will result in (the Header is being set too): +https://bittrex.com/api/v1.1/account/getbalances?currency=BTC&apikey=API_KEY&nonce=4456490600 +``` + +##### getticker +```javascript +bittrex.getticker( { market : 'BTC-LTC' }, function( data, err ) { + console.log( data ); +}); +``` + +##### getbalances +```javascript +bittrex.getbalances( function( data, err ) { + console.log( data ); +}); +``` + +##### getmarkethistory +```javascript +bittrex.getmarkethistory({ market : 'BTC-LTC' }, function( data, err ) { + console.log( data ); +}); +``` + +##### getmarketsummaries +```javascript +bittrex.getmarketsummaries( function( data, err ) { + console.log( data ); +}); +``` + +##### getmarketsummary +```javascript +bittrex.getmarketsummary( { market : 'BTC-LTC'}, function( data, err ) { + console.log( data ); +}); +``` + +##### getorderbook +```javascript +bittrex.getorderbook({ market : 'BTC-LTC', depth : 10, type : 'both' }, function( data, err ) { + console.log( data ); +}); +``` + +##### getwithdrawalhistory +```javascript +bittrex.getwithdrawalhistory({ currency : 'BTC' }, function( data, err ) { + console.log( data ); +}); +``` + +##### getdepositaddress +```javascript +bittrex.getdepositaddress({ currency : 'BTC' }, function( data, err ) { + console.log( data ); +}); +``` + +##### getdeposithistory +```javascript +bittrex.getdeposithistory({ currency : 'BTC' }, function( data, err ) { + console.log( data ); +}); +``` + +##### getbalance +```javascript +bittrex.getbalance({ currency : 'BTC' }, function( data, err ) { + console.log( data ); +}); +``` + +##### withdraw +```javascript +bittrex.withdraw({ currency : 'BTC', quantity : '1.5112', address : 'THE_ADDRESS' }, function( data, err ) { + console.log( data ); +}); +``` + + +Supported v2 API methods +------ + +Little is known about the v2 api at present. We have support for only a few methods +with very little documentation. Given that the v2 api is still indevelopment by +Bittrex it is possible these methods will change or become invalid without notice. + +##### getcandles +```javascript +bittrex.getcandles({ + marketName: 'USDT-BTC', + tickInterval: 'fiveMin', // intervals are keywords +}, function( data, err ) { + console.log( data ); +}); +``` + +##### tradesell +```javascript +bittrex.tradesell({ + MarketName: 'BTC-ZEC', + OrderType: 'LIMIT', + Quantity: 1.00000000, + Rate: 0.04423432, + TimeInEffect: 'IMMEDIATE_OR_CANCEL', // supported options are 'IMMEDIATE_OR_CANCEL', 'GOOD_TIL_CANCELLED', 'FILL_OR_KILL' + ConditionType: 'NONE', // supported options are 'NONE', 'GREATER_THAN', 'LESS_THAN' + Target: 0, // used in conjunction with ConditionType +}, function( data, err ) { + console.log( data ); +}); +``` + +##### tradebuy +```javascript +bittrex.tradebuy({ + MarketName: 'BTC-ZEC', + OrderType: 'LIMIT', + Quantity: 1.00000000, + Rate: 0.04423432, + TimeInEffect: 'IMMEDIATE_OR_CANCEL', // supported options are 'IMMEDIATE_OR_CANCEL', 'GOOD_TIL_CANCELLED', 'FILL_OR_KILL' + ConditionType: 'NONE', // supported options are 'NONE', 'GREATER_THAN', 'LESS_THAN' + Target: 0, // used in conjunction with ConditionType +}, function( data, err ) { + console.log( data ); +}); +``` + + +Testing +---- + +Installing test gear +```bash +npm install --only=dev +``` + +Running all tests +```bash +npm test tests +``` + +or individually +```bash +npm test tests/public.js +npm test tests/private.js +``` + +##### Testing private methods + +Testing private method endpoints requires an api key/secret which should be +installed in to ``tests/config.json`` - you will find an example file in +``tests/config_example.json``. + +```bash +cp tests/tests_example.json tests/config.json +vim tests/config.json +``` + diff --git a/package.json b/package.json index 39986b7..132a443 100644 --- a/package.json +++ b/package.json @@ -33,9 +33,12 @@ }, "homepage": "https://github.com/dparlevliet/node.bittrex.api", "scripts": { - "test": "mocha" + "test": "mocha", + "docs": "jsdoc2md --template jsdoc2md/README.hbs --files node.bittrex.api.js > README.md", + "docs-json": "jsdoc2md --json node.bittrex.api.js" }, "devDependencies": { + "jsdoc-to-markdown": "^3.0.2", "mocha": "^3.3.0" } }