Release v3.6.0

CHANGELOG.md

@@ -1,4 +1,17 @@
 # Changelog
+
+## 3.6.0 - 2024-12-19
+
+### Added
+- A new optional parameter `timeUnit` can be used to select the time unit. Available options are `MILLISECOND`, `MICROSECOND`, `millisecond` and `microsecond`.
+
+### Changed
+- Use signed requests for the following endpoints:
+  - `POST /sapi/v1/lending/auto-invest/plan/edit-status`
+  - `GET /sapi/v1/lending/auto-invest/plan/list`
+  - `GET /sapi/v1/lending/auto-invest/plan/id`
+  - `GET /sapi/v1/lending/auto-invest/history/list`
+
 ## 3.5.0 - 2024-10-02
 ### Added
 - Add GiftCard endpoint:

README.md

@@ -110,7 +110,24 @@ const apiSecret = ''
 const client = new Spot(apiKey, apiSecret)
 
 client.account({ recvWindow: 2000 }).then(response => client.logger.log(response.data))
+```
+
+### Time Unit
+
+The API supports different time units for timestamp values. By default, timestamp values are provided in milliseconds. You can specify the time unit in the request parameters:
 
+```javascript
+const { Spot, TimeUnit } = require('@binance/connector')
+
+const apiKey = ''
+const apiSecret = ''
+const client = new Spot(apiKey, apiSecret)
+
+// Using milliseconds (default)
+client.exchangeInfo({ timeUnit: TimeUnit.MILLISECOND }).then(response => client.logger.log(response.data))
+
+// Using microseconds 
+client.exchangeInfo({ timeUnit: TimeUnit.MICROSECOND }).then(response => client.logger.log(response.data))
 ```
 
 ### Timeout
@@ -255,12 +272,12 @@ const callbacks = {
   message: data => logger.info(data)
 }
 
-const websocketStreamClient = new WebsocketStream({ logger, callbacks })
+// initialize websocket stream with microseconds as the preferred time unit
+const websocketStreamClient = new WebsocketStream({ logger, callbacks, timeUnit: TimeUnit.MICROSECOND })
 // subscribe ticker stream
 websocketStreamClient.ticker('bnbusdt')
 // close websocket stream
 setTimeout(() => websocketStreamClient.disconnect(), 6000)
-
 ```
 
 ### Unsubscribe Websocket Stream
@@ -273,7 +290,7 @@ websocketStreamClient.unsubscribe('bnbusdt@kline_1m')
 ### WebSocket API
 
 ```javascript
-const { WebsocketAPI } = require('@binance/connector')
+const { WebsocketAPI, TimeUnit } = require('@binance/connector')
 const logger = new Console({ stdout: process.stdout, stderr: process.stderr })
 
 // callbacks for different events
@@ -288,7 +305,8 @@ const callbacks = {
   message: data => logger.info(data)
 }
 
-const websocketAPIClient = new WebsocketAPI(null, null, { logger, callbacks })
+// initialize WebsocketAPI client with microseconds as the preferred time unit
+const websocketAPIClient = new WebsocketAPI(null, null, { logger, callbacks, timeUnit: TimeUnit.MICROSECOND })
 
 // disconnect the connection
 setTimeout(() => websocketAPIClient.disconnect(), 20000)

__tests__/helpers/utils.test.js

@@ -1,5 +1,5 @@
 /* global describe, it, expect */
-const { isEmptyValue, removeEmptyValue, buildQueryString, flowRight, sortObject } = require('../../src/helpers/utils')
+const { isEmptyValue, removeEmptyValue, removeTimeUnit, buildQueryString, flowRight, sortObject } = require('../../src/helpers/utils')
 
 describe('#isEmptyValue', () => {
   it.each([
@@ -45,6 +45,23 @@ describe('#removeEmptyValue', () => {
   })
 })
 
+describe('#removeTimeUnit', () => {
+  it('should be the same without a timeUnit field', () => {
+    const obj = { foo: 'bar' }
+    expect(removeTimeUnit(obj)).toBe(obj)
+  })
+
+  it.each(
+    [
+      [{ key1: 'value1', timeUnit: 'MICROSECOND' }, { key1: 'value1' }],
+      [{ timeUnit: 'MICROSECOND' }, { }],
+      [{ key1: true, timeUnit: 'MICROSECOND', key3: false }, { key1: true, key3: false }]
+    ]
+  )('should remove the timeUnit field', (obj, expectedObj) => {
+    expect(removeTimeUnit(obj)).toStrictEqual(expectedObj)
+  })
+})
+
 describe('#buildQueryString', () => {
   it.each`
   inputObj | output

__tests__/helpers/validation.test.js

@@ -1,6 +1,7 @@
 /* global describe, it, expect */
-const { validateRequiredParameters, hasOneOfParameters } = require('../../src/helpers/validation')
+const { validateRequiredParameters, hasOneOfParameters, validateTimeUnit } = require('../../src/helpers/validation')
 const MissingParameterError = require('../../src/error/missingParameterError')
+const ConnectorClientError = require('../../src/error/connectorClientError')
 
 describe('#validateRequiredParameters', () => {
   it('should throw error without parameter', () => {
@@ -74,3 +75,28 @@ describe('#hasOneOfParameters', () => {
     }).not.toThrow(MissingParameterError)
   })
 })
+
+describe('#validateTimeUnit', () => {
+  it('should not throw an error if timeUnit is not defined', () => {
+    expect(() => {
+      validateTimeUnit()
+    }).not.toThrow(ConnectorClientError)
+  })
+
+  it.each([
+    'MICROSECOND',
+    'MILLISECOND'
+  ])('should not throw an error when timeUnit is valid', (timeUnit) => {
+    expect(() => {
+      validateTimeUnit(timeUnit)
+    }).not.toThrow(ConnectorClientError)
+  })
+
+  it.each([
+    'random string'
+  ])('should throw an error when timeUnit is invalid', (timeUnit) => {
+    expect(() => {
+      validateTimeUnit(timeUnit)
+    }).toThrow(ConnectorClientError)
+  })
+})

__tests__/spot/margin/isolatedMarginAccountLimit.test.js

@@ -11,5 +11,4 @@ describe('#isolatedMarginAccountLimit', () => {
       expect(response.data).toEqual(mockResponse)
     })
   })
-}
-)
+})

__tests__/spot/margin/isolatedMarginAllSymbols.test.js

@@ -11,5 +11,4 @@ describe('#isolatedMarginAllSymbols', () => {
       expect(response.data).toEqual(mockResponse)
     })
   })
-}
-)
+})

__tests__/spot/market/aggTrades.test.js

@@ -1,7 +1,7 @@
 /* global describe, it, expect */
 const MissingParameterError = require('../../../src/error/missingParameterError')
 const { nockMock, SpotClient } = require('../../testUtils/testSetup')
-const { mockResponse } = require('../../testUtils/mockData')
+const { mockResponse, timeUnit } = require('../../testUtils/mockData')
 
 describe('#aggTrades', () => {
   describe('throw MissingParameterError', () => {
@@ -16,6 +16,16 @@ describe('#aggTrades', () => {
     const symbol = 'BTCUSDT'
     nockMock(`/api/v3/aggTrades?symbol=${symbol}`)(mockResponse)
 
+    return SpotClient.aggTrades(symbol, { timeUnit }).then(response => {
+      expect(response).toBeDefined()
+      expect(response.data).toEqual(mockResponse)
+    })
+  })
+
+  it('should return agg trades without optional parameters', () => {
+    const symbol = 'BTCUSDT'
+    nockMock(`/api/v3/aggTrades?symbol=${symbol}`)(mockResponse)
+
     return SpotClient.aggTrades(symbol).then(response => {
       expect(response).toBeDefined()
       expect(response.data).toEqual(mockResponse)

__tests__/spot/market/avgPrice.test.js

@@ -1,7 +1,7 @@
 /* global describe, it, expect */
 const MissingParameterError = require('../../../src/error/missingParameterError')
 const { nockMock, SpotClient } = require('../../testUtils/testSetup')
-const { mockResponse } = require('../../testUtils/mockData')
+const { mockResponse, timeUnit } = require('../../testUtils/mockData')
 
 describe('#avgPrice', () => {
   describe('throw MissingParameterError', () => {
@@ -16,6 +16,16 @@ describe('#avgPrice', () => {
     const symbol = 'BTCUSDT'
     nockMock(`/api/v3/avgPrice?symbol=${symbol}`)(mockResponse)
 
+    return SpotClient.avgPrice(symbol, { timeUnit }).then(response => {
+      expect(response).toBeDefined()
+      expect(response.data).toEqual(mockResponse)
+    })
+  })
+
+  it('should return avg price without optional parameters', () => {
+    const symbol = 'BTCUSDT'
+    nockMock(`/api/v3/avgPrice?symbol=${symbol}`)(mockResponse)
+
     return SpotClient.avgPrice(symbol).then(response => {
       expect(response).toBeDefined()
       expect(response.data).toEqual(mockResponse)

__tests__/spot/market/exchangeInfo.test.js

@@ -1,6 +1,6 @@
 /* global describe, it, expect */
 const { nockMock, buildQueryString, SpotClient } = require('../../testUtils/testSetup')
-const { mockResponse } = require('../../testUtils/mockData')
+const { mockResponse, timeUnit } = require('../../testUtils/mockData')
 
 describe('#exchangeInfo', () => {
   it('should return exchange info', () => {
@@ -12,6 +12,15 @@ describe('#exchangeInfo', () => {
     })
   })
 
+  it('should return exchange info with timeUnit specified', () => {
+    nockMock('/api/v3/exchangeInfo')(mockResponse)
+
+    return SpotClient.exchangeInfo({ timeUnit }).then(response => {
+      expect(response).toBeDefined()
+      expect(response.data).toEqual(mockResponse)
+    })
+  })
+
   it('should return exchange info with symbol specified', () => {
     const symbol = 'BTCUSDT'
     nockMock(`/api/v3/exchangeInfo?symbol=${symbol}`)(mockResponse)

__tests__/spot/market/historicalTrades.test.js

@@ -1,7 +1,7 @@
 /* global describe, it, expect */
 const MissingParameterError = require('../../../src/error/missingParameterError')
 const { nockMock, SpotClient } = require('../../testUtils/testSetup')
-const { mockResponse } = require('../../testUtils/mockData')
+const { mockResponse, timeUnit } = require('../../testUtils/mockData')
 
 describe('#historicalTrades', () => {
   describe('throw MissingParameterError', () => {
@@ -16,6 +16,16 @@ describe('#historicalTrades', () => {
     const symbol = 'BTCUSDT'
     nockMock(`/api/v3/historicalTrades?symbol=${symbol}`)(mockResponse)
 
+    return SpotClient.historicalTrades(symbol, { timeUnit }).then(response => {
+      expect(response).toBeDefined()
+      expect(response.data).toEqual(mockResponse)
+    })
+  })
+
+  it('should return historical trades without optional parameters', () => {
+    const symbol = 'BTCUSDT'
+    nockMock(`/api/v3/historicalTrades?symbol=${symbol}`)(mockResponse)
+
     return SpotClient.historicalTrades(symbol).then(response => {
       expect(response).toBeDefined()
       expect(response.data).toEqual(mockResponse)

__tests__/spot/market/klines.test.js

@@ -1,7 +1,7 @@
 /* global describe, it, expect */
 const MissingParameterError = require('../../../src/error/missingParameterError')
 const { nockMock, SpotClient } = require('../../testUtils/testSetup')
-const { mockResponse } = require('../../testUtils/mockData')
+const { mockResponse, timeUnit } = require('../../testUtils/mockData')
 
 describe('#klines', () => {
   describe('throw MissingParameterError', () => {
@@ -23,6 +23,17 @@ describe('#klines', () => {
     const interval = '1m'
     nockMock(`/api/v3/klines?symbol=${symbol}&interval=${interval}`)(mockResponse)
 
+    return SpotClient.klines(symbol, interval, { timeUnit }).then(response => {
+      expect(response).toBeDefined()
+      expect(response.data).toEqual(mockResponse)
+    })
+  })
+
+  it('should return klines without optional parameters', () => {
+    const symbol = 'BTCUSDT'
+    const interval = '1m'
+    nockMock(`/api/v3/klines?symbol=${symbol}&interval=${interval}`)(mockResponse)
+
     return SpotClient.klines(symbol, interval).then(response => {
       expect(response).toBeDefined()
       expect(response.data).toEqual(mockResponse)

__tests__/spot/market/rollingWindowTicker.test.js

@@ -1,6 +1,6 @@
 /* global describe, it, expect */
 const { nockMock, buildQueryString, SpotClient } = require('../../testUtils/testSetup')
-const { mockResponse } = require('../../testUtils/mockData')
+const { mockResponse, timeUnit } = require('../../testUtils/mockData')
 
 describe('#rollingWindowTicker', () => {
   it('should return ticker for selective pairs', () => {
@@ -33,4 +33,14 @@ describe('#rollingWindowTicker', () => {
       expect(response.data).toEqual(mockResponse)
     })
   })
+
+  it('should return ticker price for specific unit of time', () => {
+    const symbol = 'BTCUSDT'
+    nockMock(`/api/v3/ticker?symbol=${symbol}`)(mockResponse)
+
+    return SpotClient.rollingWindowTicker(symbol, [], { timeUnit }).then(response => {
+      expect(response).toBeDefined()
+      expect(response.data).toEqual(mockResponse)
+    })
+  })
 })

__tests__/spot/market/ticker24hr.test.js

@@ -1,6 +1,6 @@
 /* global describe, it, expect */
 const { nockMock, buildQueryString, SpotClient } = require('../../testUtils/testSetup')
-const { mockResponse } = require('../../testUtils/mockData')
+const { mockResponse, timeUnit } = require('../../testUtils/mockData')
 const DEFAULT_TYPE = 'FULL'
 
 describe('#ticker24hr', () => {
@@ -13,6 +13,15 @@ describe('#ticker24hr', () => {
     })
   })
 
+  it('should return 24hr price for all pairs with optional parameters', () => {
+    nockMock(`/api/v3/ticker/24hr?type=${DEFAULT_TYPE}`)(mockResponse)
+
+    return SpotClient.ticker24hr('', [], 'FULL', { timeUnit }).then(response => {
+      expect(response).toBeDefined()
+      expect(response.data).toEqual(mockResponse)
+    })
+  })
+
   it('should return 24hr price for selective pairs', () => {
     const symbols = ['BTCUSDT', 'BNBUSDT']
     nockMock(`/api/v3/ticker/24hr?${buildQueryString({ symbols, type: DEFAULT_TYPE })}`)(mockResponse)

__tests__/spot/market/time.test.js

@@ -1,11 +1,20 @@
 /* global describe, it, expect */
 const { nockMock, SpotClient } = require('../../testUtils/testSetup')
-const { mockResponse } = require('../../testUtils/mockData')
+const { mockResponse, timeUnit } = require('../../testUtils/mockData')
 
 describe('#time', () => {
   it('should return server time', () => {
     nockMock('/api/v3/time')(mockResponse)
 
+    return SpotClient.time({ timeUnit }).then(response => {
+      expect(response).toBeDefined()
+      expect(response.data).toEqual(mockResponse)
+    })
+  })
+
+  it('should return server time without optional parameters', () => {
+    nockMock('/api/v3/time')(mockResponse)
+
     return SpotClient.time().then(response => {
       expect(response).toBeDefined()
       expect(response.data).toEqual(mockResponse)

__tests__/spot/market/trades.test.js

@@ -1,7 +1,7 @@
 /* global describe, it, expect */
 const MissingParameterError = require('../../../src/error/missingParameterError')
 const { nockMock, SpotClient } = require('../../testUtils/testSetup')
-const { mockResponse } = require('../../testUtils/mockData')
+const { mockResponse, timeUnit } = require('../../testUtils/mockData')
 
 describe('#trades', () => {
   describe('throw MissingParameterError', () => {
@@ -16,6 +16,16 @@ describe('#trades', () => {
     const symbol = 'BTCUSDT'
     nockMock(`/api/v3/trades?symbol=${symbol}`)(mockResponse)
 
+    return SpotClient.trades(symbol, { timeUnit }).then(response => {
+      expect(response).toBeDefined()
+      expect(response.data).toEqual(mockResponse)
+    })
+  })
+
+  it('should return trades without optional parameters', () => {
+    const symbol = 'BTCUSDT'
+    nockMock(`/api/v3/trades?symbol=${symbol}`)(mockResponse)
+
     return SpotClient.trades(symbol).then(response => {
       expect(response).toBeDefined()
       expect(response.data).toEqual(mockResponse)