Merge pull request #1139 from 0xProject/feature/website/asset-buyer-docs

[asset-buyer][monorepo-scripts][website] Add asset-buyer documentation

package.json

@@ -40,7 +40,7 @@
     },
     "config": {
         "mnemonic": "concert load couple harbor equip island argue ramp clarify fence smart topic",
-        "packagesWithDocPages": "0x.js connect json-schemas subproviders web3-wrapper contract-wrappers order-utils order-watcher sol-compiler sol-cov ethereum-types"
+        "packagesWithDocPages": "0x.js connect json-schemas subproviders web3-wrapper contract-wrappers order-utils order-watcher sol-compiler sol-cov ethereum-types asset-buyer"
     },
     "bundlewatch" : {
         "files": [

packages/asset-buyer/CHANGELOG.json

@@ -13,6 +13,18 @@
                 "note":
                     "Updated to use new modularized artifacts and the latest version of @0xproject/contract-wrappers",
                 "pr": 1105
+            },
+            {
+                "note": "Add `gasLimit` and `gasPrice` as optional properties on `BuyQuoteExecutionOpts`",
+                "pr": 1116
+            },
+            {
+                "note": "Add `docs:json` command to package.json",
+                "pr": 1139
+            },
+            {
+                "note": "Add missing types to public interface",
+                "pr": 1139
             }
         ]
     },

packages/asset-buyer/package.json

@@ -17,7 +17,8 @@
         "coverage:report:lcov": "nyc report --reporter=text-lcov > coverage/lcov.info",
         "test:circleci": "yarn test:coverage",
         "run_mocha": "mocha --require source-map-support/register --require make-promises-safe lib/test/**/*_test.js --exit",
-        "clean": "shx rm -rf lib test_temp"
+        "clean": "shx rm -rf lib test_temp",
+        "docs:json": "typedoc --excludePrivate --excludeExternals --target ES5 --tsconfig typedoc-tsconfig.json --json $JSON_FILE_PATH $PROJECT_FILES"
     },
     "config": {
         "postpublish": {

packages/asset-buyer/src/index.ts

@@ -1,4 +1,10 @@
-export { Provider } from 'ethereum-types';
+export {
+    JSONRPCRequestPayload,
+    JSONRPCResponsePayload,
+    JSONRPCResponseError,
+    JSONRPCErrorCallback,
+    Provider,
+} from 'ethereum-types';
 export { SignedOrder } from '@0xproject/types';
 export { BigNumber } from '@0xproject/utils';
 
@@ -9,8 +15,8 @@ export {
     AssetBuyerError,
     AssetBuyerOpts,
     BuyQuote,
-    BuyQuoteInfo,
     BuyQuoteExecutionOpts,
+    BuyQuoteInfo,
     BuyQuoteRequestOpts,
     OrderProvider,
     OrderProviderRequest,

packages/monorepo-scripts/CHANGELOG.json

@@ -5,6 +5,10 @@
             {
                 "note": "Render date formats in UTC to prevent conflicts when publishing in different timezones.",
                 "pr": 1143
+            },
+            {
+                "note": "Add AssetBuyerError to the IGNORED_EXCESSIVE_TYPES array",
+                "pr": 1139
             }
         ]
     },

packages/monorepo-scripts/src/doc_gen_configs.ts

@@ -30,6 +30,7 @@ export const docGenConfigs: DocGenConfigs = {
     // factory method which instantiates an instance of a class, but we don't want users instantiating it themselves
     // and getting confused. Any class name in this list will not have it's constructor rendered in our docs.
     CLASSES_WITH_HIDDEN_CONSTRUCTORS: [
+        'AssetBuyer',
         'ERC20ProxyWrapper',
         'ERC20TokenWrapper',
         'ERC721ProxyWrapper',
@@ -43,7 +44,13 @@ export const docGenConfigs: DocGenConfigs = {
     // Some types are not explicitly part of the public interface like params, return values, etc... But we still
     // want them exported. E.g error enum types that can be thrown by methods. These must be manually added to this
     // config
-    IGNORED_EXCESSIVE_TYPES: ['NonceSubproviderErrors', 'Web3WrapperErrors', 'ContractWrappersError', 'OrderError'],
+    IGNORED_EXCESSIVE_TYPES: [
+        'NonceSubproviderErrors',
+        'Web3WrapperErrors',
+        'ContractWrappersError',
+        'OrderError',
+        'AssetBuyerError',
+    ],
     // Some libraries only export types. In those cases, we cannot check if the exported types are part of the
     // "exported public interface". Thus we add them here and skip those checks.
     TYPES_ONLY_LIBRARIES: ['ethereum-types', 'types'],

packages/monorepo-scripts/src/utils/doc_generate_and_upload_utils.ts

@@ -331,7 +331,7 @@ export class DocGenerateAndUploadUtils {
             throw new Error(
                 `${this._packageName} package exports BUT does not need: \n${excessiveReferencesExceptIgnored.join(
                     '\n',
-                )} \nin it\'s index.ts. Remove them then try again.`,
+                )} \nin it\'s index.ts. Remove them then try again OR if we still want them exported (e.g error enum types), then add them to the IGNORED_EXCESSIVE_TYPES array.`,
             );
         }
     }

packages/website/md/docs/asset_buyer/installation.md

@@ -0,0 +1,17 @@
+**Install**
+
+```bash
+yarn add @0xproject/asset-buyer
+```
+
+**Import**
+
+```javascript
+import { AssetBuyer } from '@0xproject/asset-buyer';
+```
+
+or
+
+```javascript
+var AssetBuyer = require('@0xproject/asset-buyer').AssetBuyer;
+```

packages/website/md/docs/asset_buyer/introduction.md

@@ -0,0 +1 @@
+Welcome to the [@0xproject/asset-buyer](https://github.com/0xProject/0x-monorepo/tree/development/packages/asset-buyer) documentation! AssetBuyer is a library that provides an easy way to buy any asset with ETH in one click, leveraging 0x liquidity and the [Forwarder contract](https://0xproject.com/docs/contracts#Forwarder).

packages/website/md/docs/asset_buyer/usage.md

@@ -0,0 +1,39 @@
+**Construction**
+
+Connecting to a standard relayer API compliant url:
+
+```typescript
+const provider = web3.currentProvider;
+const apiUrl = 'https://api.relayer.com/v2';
+const assetBuyer = AssetBuyer.getAssetBuyerForStandardRelayerAPIUrl(provider, apiUrl);
+```
+
+Providing your own orders:
+
+```typescript
+const provider = web3.currentProvider;
+const orders = []; // get these from your own API, a relayer, a friend, from anywhere
+const assetBuyer = AssetBuyer.getAssetBuyerForProvidedOrders(provider, orders);
+```
+
+**Get a quote**
+
+A [BuyQuote](#types-BuyQuote) object contains enough information to display buy information to an end user
+
+```typescript
+const erc20TokenAddress = '0x5fa3c....';
+const amountToBuy = new BigNumber(50000000000000000000);
+const buyQuote = await assetBuyer.getBuyQuoteForERC20TokenAddressAsync(erc20TokenAddress, amountToBuy);
+const quoteInfo = buyQuote.worstCaseQuoteInfo;
+console.log(quoteInfo.ethAmount); // the total amount the user needs to pay to buy the desired amount (including ZRX fees)
+console.log(quoteInfo.feeAmount); // a portion of the total ethAmount above that was used to buy affiliate fees
+console.log(quoteInfo.ethPerAssetPrice); // the rate that this quote provides (e.g. 0.0035ETH / REP)
+```
+
+**Perform a buy**
+
+Pass the [BuyQuote](#types-BuyQuote) object from above back to the assetBuyer in order to initiate the buy transaction
+
+```typescript
+const txHash = await assetBuyer.executeBuyQuoteAsync(buyQuote); // the hash of the transaction submitted to the Ethereum network
+```

packages/website/translations/english.json

@@ -73,6 +73,7 @@
     "WIKI": "wiki",
     "WEB3_WRAPPER": "Web3Wrapper",
     "ORDER_UTILS": "Order Utils",
+    "ASSET_BUYER": "AssetBuyer",
     "FAQ": "FAQ",
     "SMART_CONTRACTS": "0x smart contracts",
     "STANDARD_RELAYER_API": "standard relayer API",

packages/website/ts/components/top_bar/top_bar.tsx

@@ -92,6 +92,7 @@ const DOC_WEBSITE_PATHS_TO_KEY = {
     [WebsitePaths.ZeroExJs]: Key.ZeroExJs,
     [WebsitePaths.OrderUtils]: Key.OrderUtils,
     [WebsitePaths.OrderWatcher]: Key.OrderWatcher,
+    [WebsitePaths.AssetBuyer]: Key.AssetBuyer,
 };
 
 const DEFAULT_HEIGHT = 68;
@@ -214,6 +215,12 @@ export class TopBar extends React.Component<TopBarProps, TopBarState> {
                     primaryText={this.props.translate.get(Key.EthereumTypes, Deco.CapWords)}
                 />
             </Link>,
+            <Link key="subMenuItem-asset-buyer" to={WebsitePaths.AssetBuyer} className="text-decoration-none">
+                <MenuItem
+                    style={{ fontSize: styles.menuItem.fontSize }}
+                    primaryText={this.props.translate.get(Key.AssetBuyer, Deco.CapWords)}
+                />
+            </Link>,
             <a
                 key="subMenuItem-whitePaper"
                 target="_blank"

packages/website/ts/containers/asset_buyer_documentation.ts

@@ -0,0 +1,69 @@
+import { DocsInfo, DocsInfoConfig, SupportedDocJson } from '@0xproject/react-docs';
+import * as React from 'react';
+import { connect } from 'react-redux';
+import { Dispatch } from 'redux';
+import { DocPage as DocPageComponent, DocPageProps } from 'ts/pages/documentation/doc_page';
+import { Dispatcher } from 'ts/redux/dispatcher';
+import { State } from 'ts/redux/reducer';
+import { DocPackages } from 'ts/types';
+import { Translate } from 'ts/utils/translate';
+
+/* tslint:disable:no-var-requires */
+const IntroMarkdown = require('md/docs/asset_buyer/introduction');
+const InstallationMarkdown = require('md/docs/asset_buyer/installation');
+const UsageMarkdown = require('md/docs/asset_buyer/usage');
+/* tslint:enable:no-var-requires */
+
+const markdownSections = {
+    introduction: 'introduction',
+    installation: 'installation',
+    usage: 'usage',
+};
+
+const docsInfoConfig: DocsInfoConfig = {
+    id: DocPackages.AssetBuyer,
+    packageName: '@0xproject/asset-buyer',
+    type: SupportedDocJson.TypeDoc,
+    displayName: 'AssetBuyer',
+    packageUrl: 'https://github.com/0xProject/0x-monorepo',
+    markdownMenu: {
+        introduction: [markdownSections.introduction],
+        install: [markdownSections.installation],
+        usage: [markdownSections.usage],
+    },
+    sectionNameToMarkdownByVersion: {
+        '0.0.1': {
+            [markdownSections.introduction]: IntroMarkdown,
+            [markdownSections.installation]: InstallationMarkdown,
+            [markdownSections.usage]: UsageMarkdown,
+        },
+    },
+    markdownSections,
+};
+const docsInfo = new DocsInfo(docsInfoConfig);
+
+interface ConnectedState {
+    docsVersion: string;
+    availableDocVersions: string[];
+    docsInfo: DocsInfo;
+    translate: Translate;
+}
+
+interface ConnectedDispatch {
+    dispatcher: Dispatcher;
+}
+
+const mapStateToProps = (state: State, _ownProps: DocPageProps): ConnectedState => ({
+    docsVersion: state.docsVersion,
+    availableDocVersions: state.availableDocVersions,
+    translate: state.translate,
+    docsInfo,
+});
+
+const mapDispatchToProps = (dispatch: Dispatch<State>): ConnectedDispatch => ({
+    dispatcher: new Dispatcher(dispatch),
+});
+
+export const Documentation: React.ComponentClass<DocPageProps> = connect(mapStateToProps, mapDispatchToProps)(
+    DocPageComponent,
+);

packages/website/ts/index.tsx

@@ -68,6 +68,9 @@ const LazyOrderUtilsDocumentation = createLazyComponent('Documentation', async (
 const LazyEthereumTypesDocumentation = createLazyComponent('Documentation', async () =>
     import(/* webpackChunkName: "ethereumTypesDocs" */ 'ts/containers/ethereum_types_documentation'),
 );
+const LazyAssetBuyerDocumentation = createLazyComponent('Documentation', async () =>
+    import(/* webpackChunkName: "assetBuyerDocs" */ 'ts/containers/asset_buyer_documentation'),
+);
 
 const DOCUMENT_TITLE = '0x: The Protocol for Trading Tokens';
 const DOCUMENT_DESCRIPTION = 'An Open Protocol For Decentralized Exchange On The Ethereum Blockchain';
@@ -133,7 +136,10 @@ render(
                                     path={`${WebsitePaths.EthereumTypes}/:version?`}
                                     component={LazyEthereumTypesDocumentation}
                                 />
-
+                                <Route
+                                    path={`${WebsitePaths.AssetBuyer}/:version?`}
+                                    component={LazyAssetBuyerDocumentation}
+                                />
                                 {/* Legacy endpoints */}
                                 <Route
                                     path={`${WebsiteLegacyPaths.ZeroExJs}/:version?`}

packages/website/ts/pages/documentation/doc_page.tsx

@@ -43,6 +43,7 @@ const docIdToSubpackageName: { [id: string]: string } = {
     [DocPackages.OrderUtils]: 'order-utils',
     [DocPackages.OrderWatcher]: 'order-watcher',
     [DocPackages.EthereumTypes]: 'ethereum-types',
+    [DocPackages.AssetBuyer]: 'asset-buyer',
 };
 
 export interface DocPageProps {

packages/website/ts/types.ts

@@ -363,6 +363,7 @@ export enum WebsitePaths {
     Subproviders = '/docs/subproviders',
     OrderUtils = '/docs/order-utils',
     EthereumTypes = '/docs/ethereum-types',
+    AssetBuyer = '/docs/asset-buyer',
     Careers = '/careers',
 }
 
@@ -379,6 +380,7 @@ export enum DocPackages {
     EthereumTypes = 'ETHEREUM_TYPES',
     ContractWrappers = 'CONTRACT_WRAPPERS',
     OrderWatcher = 'ORDER_WATCHER',
+    AssetBuyer = 'ASSET_BUYER',
 }
 
 export enum Key {
@@ -440,6 +442,7 @@ export enum Key {
     ZeroExJs = '0X_JS',
     ContractWrappers = 'CONTRACT_WRAPPERS',
     OrderWatcher = 'ORDER_WATCHER',
+    AssetBuyer = 'ASSET_BUYER',
     Blog = 'BLOG',
     Forum = 'FORUM',
     Connect = 'CONNECT',