feat(contract): Merge master

Author: taylorjdawson

dist/web3data.min.js

@@ -3,7 +3,14 @@ const {
   ADDRESSES_ENDPOINT: ENDPOINT
 } = require('./constants')
 
-const {is, get, throwIf, onFulfilled, onError} = require('./utils')
+const {
+  is,
+  get,
+  throwIf,
+  onFulfilled,
+  onError,
+  recordsFormatter
+} = require('./utils')
 
 /**
  * Contains methods pertaining to the `/address` endpoint of Amberdata's API.
@@ -19,21 +26,33 @@ class Address {
     this.web3data = web3data
   }
 
+  /**
+   * Alias of getAll().
+   *
+   * @param [filterOptions] - The filters associated with the request.
+   * @example web3data.address.getAllAddresses({
+   * size: 100,
+   * })
+   */
+  getAllAddresses(filterOptions = {}) {
+    return this.getAll(filterOptions)
+  }
+
   /**
    * Returns every address that has been seen on the network.
    *
    * @param filterOptions - The filters associated with the request.
    * @param [filterOptions.hash] - Filter by a specific address.
    * @param [filterOptions.size] - The size of the response. <b>Default:</b> `100`.
-   * @returns Containing an object with an array of objects containing. See [API docs](https://docs.amberdata.io/reference#get-all-addresses) for details on return.
+   * @returns Containing an object with an array of objects containing. See [API docs](https://docs.amberdata.io/reference#get-all-addresses) for details on response.
    * @public
-   * @example web3data.address.getAllAddresses({
+   * @example web3data.address.getAll({
    * size: 100,
    * })
    */
-  getAllAddresses(filterOptions = {}) {
+  getAll(filterOptions = {}) {
     return get(this.web3data, {endpoint: ENDPOINT, filterOptions}).then(
-      onFulfilled,
+      onFulfilled.bind({formatter: recordsFormatter}),
       onError
     )
   }
@@ -58,8 +77,17 @@ class Address {
     }).then(onFulfilled, onError)
   }
 
+  /**
+   * Retrieves the historical adoption for the specified address.
+   *
+   * @param hash - The address.
+   * @param [filterOptions] - The filters associated with the request. See [API docs](https://docs.amberdata.io/reference#get-address-adoption) for details.
+   * @returns The historical adoption data for the specified address.
+   * @example
+   * const adoption = await web3data.address.getAdoption('0x06012c8cf97bead5deae237070f9587f8e7a266d')
+   */
   getAdoption(hash, filterOptions) {
-    if (is.notHash(hash)) return Promise.reject(new Error(NO_ADDRESS))
+    throwIf(is.notHash(hash), NO_ADDRESS)
     return get(this.web3data, {
       hash,
       endpoint: ENDPOINT,
@@ -308,8 +336,16 @@ Returns null if no address is found.
     }).then(onFulfilled, onError)
   }
 
+  /**
+   * Retrieves the historical usage for the specified address.
+   *
+   * @param hash - The address.
+   * @param [filterOptions] - The filters associated with the request. See [API docs](https://docs.amberdata.io/reference#get-address-usage) for details.
+   * @returns The usage statistics for the specified address.
+   * @example const usage = await web3data.address.getUsage(ADDRESS)
+   */
   getUsage(hash, filterOptions) {
-    if (is.notHash(hash)) return Promise.reject(new Error(NO_ADDRESS))
+    throwIf(is.notHash(hash), NO_ADDRESS)
     return get(this.web3data, {
       hash,
       endpoint: ENDPOINT,
@@ -318,12 +354,17 @@ Returns null if no address is found.
     }).then(onFulfilled, onError)
   }
 
-  // TODO: Needs tests
-  getMetrics(filterOptions) {
+  /**
+   * Get metrics for all addresses that have exist publicly for a given blockchain. Default metrics are for Ethereum over a 24h period.
+   *
+   * @returns The address metrics.
+   * @example
+   * const metrics = await web3data.address.getMetrics(ADDRESS)
+   */
+  getMetrics() {
     return get(this.web3data, {
       endpoint: ENDPOINT,
-      subendpoint: 'metrics/latest',
-      filterOptions
+      subendpoint: 'metrics/latest'
     }).then(onFulfilled, onError)
   }
 }

dist/web3data.min.js.map

@@ -12,19 +12,63 @@ const {
   recordsFormatter
 } = require('./utils')
 
+/**
+ * Contains methods pertaining to the `/address` endpoint of Amberdata's API.
+ * See [documentation](https://docs.amberdata.io/reference#get-all-transactions) details about our transaction endpoints.
+ */
 class Transaction {
+  /**
+   * Creates an instance of Transaction. Meant to be used in conjunction with the Web3Data class.
+   *
+   * @param web3data - The web3data instance.
+   * @example
+   */
   constructor(web3data) {
     this.web3data = web3data
   }
 
-  getTransactions(filterOptions) {
+  /**
+   * Retrieves all transactions matching the specified filters.
+   *
+   * @param [filterOptions] - The filter options associated with the request.
+   * @param [filterOptions.status] - Filter by the status of the transactions to retrieve (all, completed, failed, pending).
+   * @param [filterOptions.includePrice] - Indicates whether or not to include price data with the results.
+   * @returns All transactions matched by the specified filters.
+   * @example const transactions = await web3data.transaction.getTransactions()
+   *
+   * // Include pricing data with transactions
+   * const transactions = await web3data.transaction.getTransactions({
+   * includePrice: true
+   * })
+   */
+  getTransactions(filterOptions = {}) {
     return get(this.web3data, {
       endpoint: ENDPOINT,
       filterOptions
     }).then(onFulfilled.bind({formatter: recordsFormatter}), onError)
   }
 
-  getTransaction(hash, filterOptions) {
+  /**
+   * See 'getTransactions' for details.
+   *
+   * @param filterOptions
+   * @example
+   */
+  getAll(filterOptions) {
+    return this.getTransactions(filterOptions)
+  }
+
+  /**
+   * Retrieves the transaction data for the specified hash.
+   *
+   * @param hash - The transaction hash.
+   * @param [filterOptions] - The filter options associated with the request. See [docs](https://docs.amberdata.io/reference#get-transaction) for more details.
+   * @param [filterOptions.validationMethod=none] - The validation method to be added to the response: `none`, `basic`, `full`.
+   * @param [filterOptions.includePrice=true] - Indicates whether or not to include price data with the results.
+   * @returns The data for the specified transaction hash.
+   * @example const transaction = await web3data.transaction.getTransaction('0xd0a5a0912fdf87993b3cebd696f1ee667a8fbbe8fc890a22dcbdf114f36de4cf')
+   */
+  getTransaction(hash, filterOptions = {}) {
     throwIf(is.notHash(hash), NO_HASH)
     return get(this.web3data, {
       pathParam: hash,
@@ -33,6 +77,12 @@ class Transaction {
     }).then(onFulfilled, onError)
   }
 
+  /**
+   * Retrieves all pending transaction.
+   *
+   * @returns The pending transactions.
+   * @example const pendingTransactions = await web3data.transaction.getPendingTransactions()
+   */
   getPendingTransactions() {
     return this.getTransactions({status: 'pending'}).then(
       pendingTransactions => {
@@ -46,21 +96,44 @@ class Transaction {
     )
   }
 
+  /**
+   * Retrieves the latest gas predictions for the transactions.
+   *
+   * @returns The latest gas predictions for the transactions.
+   * @example
+   * const gasPredictions = await web3data.transaction.getGasPrediction()
+   */
   getGasPrediction() {
     return get(this.web3data, {
       endpoint: ENDPOINT,
       subendpoint: 'gas/predictions'
     }).then(onFulfilled, onError)
   }
 
-  getGasPercentiles(filterOptions) {
+  /**
+   * Retrieves the latest gas price percentiles for the transactions.
+   *
+   * @param [filterOptions] - The filter options associated with the request.
+   * @param [filterOptions.numBlocks] - Number of past blocks on which to base the percentiles.
+   * @returns The latest gas price percentiles for the transactions.
+   * @example
+   * const gasPercentiles = await web3data.transaction.getGasPercentiles()
+   */
+  getGasPercentiles(filterOptions = {}) {
     return get(this.web3data, {
       endpoint: ENDPOINT,
       subendpoint: 'gas/percentiles',
       filterOptions
     }).then(onFulfilled, onError)
   }
 
+  /**
+   * Retrieves the latest average gas price. Uses `getGasPrediction` under the hood.
+   *
+   * @returns The latest gas price.
+   * @example
+   * const gasPrice = await web3data.transaction.getGasPrice()
+   */
   getGasPrice() {
     return this.getGasPrediction().then(gasPrediction => {
       throwIf(
@@ -71,15 +144,31 @@ class Transaction {
     })
   }
 
-  getVolume(filterOptions) {
+  /**
+   * Retrieves the historical (time series) volume of transactions.
+   *
+   * @param [filterOptions] - The filter options associated with the request. See [docs](https://docs.amberdata.io/reference#get-historical-transaction-volume) for more details.
+   * @returns The historical (time series) volume of transactions.
+   * @example
+   * const volume = await web3data.transaction.getVolume()
+   */
+  getVolume(filterOptions = {}) {
     return get(this.web3data, {
       endpoint: ENDPOINT,
       subendpoint: 'volume',
       filterOptions
     }).then(onFulfilled, onError)
   }
 
-  getMetrics(filterOptions) {
+  /**
+   * Get metrics for recent confirmed transactions for a given blockchain. Default metrics are over a 24h period.
+   *
+   * @returns Metrics for recent confirmed transactions.
+   * @example
+   * const metrics = await web3data.transaction.getMetrics()
+   *
+   */
+  getMetrics(filterOptions = {}) {
     return get(this.web3data, {
       endpoint: ENDPOINT,
       subendpoint: 'metrics/latest',

docs/api.md

@@ -1,7 +1,12 @@
 import test, {only} from "ava"
 import {ADDRESS } from './constants'
 import {ERROR_MESSAGE_ADDRESS_NO_ADDRESS as NO_ADDRESS} from "../src/constants";
-import {setUpPolly, hasProp, getNewWeb3DataInstance} from "./utils";
+import {
+    setUpPolly,
+    hasProp,
+    getNewWeb3DataInstance,
+    isISOFormat
+} from "./utils";
 
 /**********************************
  * -------- Tests Setup ---------- *
@@ -22,11 +27,30 @@ test.beforeEach(t => {
  * -------- Test address -------- *
  **********************************/
 
+/*********** Test getAll() ***********/
+test('Successfully calls getAll()', async t => {
+    const [addresses] = await t.context.web3data.address.getAll()
+    t.true(addresses.hasProp('firstBlockNumber'))
+})
+
+test('Successfully calls getAll() - with filters', async t => {
+    const [addresses] = await t.context.web3data.address.getAll({type: 'CONTRACT'})
+    t.true(addresses.hasProp('type'))
+    t.is(addresses.type.toUpperCase(), 'CONTRACT')
+    t.true(addresses.creator !== null)
+})
+
 /*********** Test getAllAddresses() ***********/
-test('Successfully gets all addresses', async t => {
-    let addresses = await t.context.web3data.address.getAllAddresses()
-    t.true({}.hasOwnProperty.call(addresses, 'records'))
-    t.true({}.hasOwnProperty.call(addresses, 'totalRecords'))
+test('Successfully calls getAllAddresses()', async t => {
+    const [addresses] = await t.context.web3data.address.getAllAddresses()
+    t.true(addresses.hasProp('firstBlockNumber'))
+})
+
+test('Successfully calls getAllAddresses() - with filters', async t => {
+    const [addresses] = await t.context.web3data.address.getAllAddresses({type: 'CONTRACT'})
+    t.true(addresses.hasProp('type'))
+    t.is(addresses.type.toUpperCase(), 'CONTRACT')
+    t.true(addresses.creator !== null)
 })
 
 /*********** Test getInformation() ***********/
@@ -69,10 +93,19 @@ test('Successfully gets address metadata - with filters', async t => {
 })
 
 /*********** Test getAdoption() ***********/
-test('Successfully gets address adoption', async t => {
-    const response = await t.context.web3data.address.getAdoption(ADDRESS)
-    t.true({}.hasOwnProperty.call(response, 'metadata'))
+test('Successfully calls getAdoption()', async t => {
+    const adoption = await t.context.web3data.address.getAdoption(ADDRESS)
+    t.true(adoption.hasProp('metadata'))
+    t.true(adoption.metadata.hasProp('columns'))
 })
+
+test('Successfully calls getAdoption() - with filters', async t => {
+    const adoption = await t.context.web3data.address.getAdoption(ADDRESS, {timeFormat: 'iso'})
+    t.true(adoption.hasProp('metadata'))
+    t.true(adoption.metadata.hasProp('columns'))
+    t.true(isISOFormat(adoption.metadata.startDate))
+})
+
 test('throws exception when calling getAdoption without hash', async t => {
     await t.throwsAsync(async () => {
         await t.context.web3data.address.getAdoption()
@@ -237,9 +270,15 @@ test('throws exception when calling getTokenBalances without hash', async t => {
 })
 
 /*********** Test getUsage() ***********/
-test('Successfully gets address usage', async t => {
-    const response = await t.context.web3data.address.getUsage(ADDRESS)
-    t.true({}.hasOwnProperty.call(response, 'metadata'))
+test('Successfully calls getUsage()', async t => {
+    const usage = await t.context.web3data.address.getUsage(ADDRESS)
+    t.true(usage.hasProp('metadata'))
+})
+
+test('Successfully calls getUsage() - with filters', async t => {
+    const usage = await t.context.web3data.address.getUsage(ADDRESS, {timeFormat: 'iso'})
+    t.true(usage.hasProp('metadata'))
+    t.true(isISOFormat(usage.metadata.startDate))
 })
 
 test('throws exception when calling getUsage without hash', async t => {
@@ -372,3 +411,9 @@ test('Successfully gets historical address balance + paginates properly', async
     const balance = await t.context.web3data.address.getBalance(ADDRESS, {startDate: 1506184430, page: 0, size: SIZE})
     t.is(balance.data.length, SIZE)
 })
+
+/*********** Test getMetrics() ***********/
+test('Successfully calls getMetrics()', async t => {
+    const metrics = await t.context.web3data.address.getMetrics(ADDRESS)
+    t.true(metrics.hasProp('activeTotal'))
+})