Document http client (#32)

* Document PythHttpClient

* ignore intellij files

* update changelog

* fix lint

* bad test

* 2.6.2

* bump version again

* 2.6.3

Co-authored-by: Jayant Krishnamurthy <[email protected]>

Author: jayantk

Diff for: .gitignore

@@ -1,2 +1,6 @@
 node_modules
-/lib
+/lib
+
+# IntelliJ temp files
+.idea
+*.iml

Diff for: CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 2.6.3
+
+### Changed
+- Renamed websocket usage example to `example_ws_usage.ts`
+- Updated documentation to describe usage for `PythHttpClient`
+
+### Added
+- Example code for using the http client in `example_http_usage.ts`
+
 ## 2.6.1
 
 ### Changed

Diff for: README.md

@@ -22,13 +22,17 @@ $ yarn add @pythnetwork/client
 
 ## Example Usage
 
-This library provides a subscription model for consuming price updates:
+This library lets you consume prices in two different ways: you can either get continuously-streaming price updates via a websocket connection, or send one-off requests every time you want the current price.  
 
-```javascript
+### Streaming updates
+
+The websocket connection provides a subscription model for consuming price updates:
+
+```typescript
 const pythConnection = new PythConnection(solanaWeb3Connection, getPythProgramKeyForCluster(solanaClusterName))
 pythConnection.onPriceChange((product, price) => {
   // sample output:
-  // SRM/USD: $8.68725 ±$0.0131
+  // Crypto.SRM/USD: $8.68725 ±$0.0131 Status: Trading
   console.log(`${product.symbol}: $${price.price} \xB1$${price.confidence} Status: ${PriceStatus[price.status]}`)
 })
 
@@ -41,12 +45,33 @@ This callback gets two arguments:
 * `price` contains the official Pyth price and confidence, along with the component prices that were combined to produce this result.
 * `product` contains metadata about the price feed, such as the symbol (e.g., "BTC/USD") and the number of decimal points.
 
-See `src/example_usage.ts` for a runnable example of the above usage.
-You can run this example with `npm run example`.
+See `src/example_ws_usage.ts` for a runnable example of the above usage.
+You can run this example with `npm run ws_example`.
 
 You may also register to specific account updates using `connection.onAccountChange` in the solana web3 API, then
 use the methods in `index.ts` to parse the on-chain data structures into Javascript-friendly objects.
 
+### Request an update
+
+The request model allows you to send one-off HTTP requests to get the current price without subscribing to ongoing updates:
+
+```typescript
+const pythClient = new PythHttpClient(connection, pythPublicKey);
+const data = await pythClient.getData();
+
+for (let symbol of data.symbols) {
+  const price = data.productPrice.get(symbol)!;
+  // Sample output:
+  // Crypto.SRM/USD: $8.68725 ±$0.0131 Status: Trading
+  console.log(`${symbol}: $${price.price} \xB1$${price.confidence} Status: ${PriceStatus[price.status]}`)
+}
+```
+
+The `getData` function will fetch all information about every product listed on Pyth.
+This includes the current price as well as metadata, such as the base and quote currencies.
+See `src/example_http_usage.ts` for a runnable example of the above usage.
+You can run this example with `npm run http_example`.
+
 ## Releases
 
 In order to release a new version of this library and publish it to npm, follow these steps: 

Diff for: package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@pythnetwork/client",
-  "version": "2.6.1",
+  "version": "2.6.3",
   "description": "Client for consuming Pyth price data",
   "homepage": "https://pyth.network",
   "main": "lib/index.js",
@@ -19,7 +19,8 @@
     "preversion": "npm run lint",
     "version": "npm run format && git add -A src",
     "postversion": "git push && git push --tags",
-    "example": "npm run build && node lib/example_usage.js"
+    "ws_example": "npm run build && node lib/example_ws_usage.js",
+    "http_example": "npm run build && node lib/example_http_usage.js"
   },
   "keywords": [
     "pyth",

Diff for: package.json

@@ -3,9 +3,12 @@ import { Product, PriceData, parseProductData, parsePriceData, parseBaseData, Ac
 
 export interface PythHttpClientResult {
   assetTypes: string[]
+  /** The name of each product, e.g., "Crypto.BTC/USD" */
   symbols: string[]
   products: Product[]
+  /** Metadata for each product. */
   productFromSymbol: Map<string, Product>
+  /** The current price of each product. */
   productPrice: Map<string, PriceData>
   prices: PriceData[]
 }
@@ -40,7 +43,7 @@ export class PythHttpClient {
     // Retrieve data from blockchain
     const accountList = await this.connection.getProgramAccounts(this.pythProgramKey, this.commitment)
 
-    // Popolate producs and prices
+    // Populate products and prices
     const priceDataQueue = new Array<PriceData>()
     const productAccountKeyToProduct = new Map<string, Product>()
     const currentSlot = await this.connection.getSlot(this.commitment)

Diff for: src/PythHttpClient.ts

@@ -10,21 +10,10 @@ test('PythHttpClientCall', (done) => {
     pyth_client.getData().then(
       (result) => {
         try {
-          console.log('products number: ', result.products.length)
-          console.log('asset types: ', result.assetTypes)
-          console.log('product symbols: ', result.symbols)
-
           // Find a product with symbol "SOL/USD"
           const products = result.products.filter((p) => p.symbol === 'Crypto.SOL/USD')
           expect(products.length).toBeGreaterThan(0)
 
-          // Find product prices
-          const price = result.productPrice.get(products[0].symbol)
-          expect(price).toBeDefined()
-
-          console.log('products', products)
-          console.log('price', price)
-
           done()
         } catch (cerr) {
           done(cerr)

Diff for: src/__tests__/PythNetworkRestClient-test.ts

@@ -0,0 +1,26 @@
+import { Cluster, clusterApiUrl, Connection } from '@solana/web3.js'
+import { getPythProgramKeyForCluster } from './cluster'
+import { PriceStatus, PythHttpClient } from '.'
+
+const SOLANA_CLUSTER_NAME: Cluster = 'mainnet-beta'
+const connection = new Connection(clusterApiUrl(SOLANA_CLUSTER_NAME))
+const pythPublicKey = getPythProgramKeyForCluster(SOLANA_CLUSTER_NAME)
+
+async function runQuery(): Promise<void> {
+  const pythClient = new PythHttpClient(connection, pythPublicKey)
+  const data = await pythClient.getData()
+
+  for (const symbol of data.symbols) {
+    const price = data.productPrice.get(symbol)!
+
+    if (price.price && price.confidence) {
+      // tslint:disable-next-line:no-console
+      console.log(`${symbol}: $${price.price} \xB1$${price.confidence}`)
+    } else {
+      // tslint:disable-next-line:no-console
+      console.log(`${symbol}: price currently unavailable. status is ${PriceStatus[price.status]}`)
+    }
+  }
+}
+
+runQuery()

Diff for: src/example_http_usage.ts

@@ -1,9 +1,9 @@
-import { Cluster, clusterApiUrl, Connection, PublicKey } from '@solana/web3.js'
+import { Cluster, clusterApiUrl, Connection } from '@solana/web3.js'
 import { PythConnection } from './PythConnection'
 import { getPythProgramKeyForCluster } from './cluster'
 import { PriceStatus } from '.'
 
-const SOLANA_CLUSTER_NAME: Cluster = 'devnet'
+const SOLANA_CLUSTER_NAME: Cluster = 'mainnet-beta'
 const connection = new Connection(clusterApiUrl(SOLANA_CLUSTER_NAME))
 const pythPublicKey = getPythProgramKeyForCluster(SOLANA_CLUSTER_NAME)