feat(apps/hermes): new client package for hermes (#1653)

* add functions for v2 endpoints

* precommit

* remove oracle-swap and send-usd examples

* fix error

* fix precommit

* fix error

* replace axios with fetch

* create new hermes client package

* revert price-service changes

* update readme

* update ci workflow

* update package-lock.json

* fix cargo

* fix cargo

* fix errors

* refactor

* address comments

* address comments

* address comments

* address comments

* add CI to check hermes client api types

* fix ci

* remove ci

* add CI back

* updated generated types

* update precommit to exlcude serverTypes.d.ts

* address comments

* remove dockerfile

* address comments

* fix test

* address comments

* update package-lock.json

* rename to HermesClient

* rename HermesConnection to HermesClient

* address comments

* make openapi-zod-client dev-dep

* address comments

* add workflow

* update workflow

* update package name

.github/workflows/ci-hermes-client-api-types.yml

@@ -0,0 +1,23 @@
+name: Check Hermes Client API Types
+
+on:
+  pull_request:
+    paths: [apps/hermes/client/**]
+  push:
+    branches: [main]
+    paths: [apps/hermes/client/**]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          cache: "npm"
+      - name: Install deps
+        run: npm ci
+      - name: Generate API Types
+        run: npx lerna run generate-hermes-api-types
+      - name: Check API Types
+        run: npx lerna run check-hermes-api-types

.github/workflows/ci-hermes.yml → .github/workflows/ci-hermes-server.yml

@@ -1,11 +1,11 @@
-name: Check Hermes
+name: Check Hermes Server
 
 on:
   pull_request:
-    paths: [apps/hermes/**]
+    paths: [apps/hermes/server/**]
   push:
     branches: [main]
-    paths: [apps/hermes/**]
+    paths: [apps/hermes/server/**]
 jobs:
   test:
     runs-on: ubuntu-latest
@@ -20,4 +20,4 @@ jobs:
       - name: Install protoc
         uses: arduino/setup-protoc@v3
       - name: Run executor tests
-        run: cargo test --manifest-path ./apps/hermes/Cargo.toml
+        run: cargo test --manifest-path ./apps/hermes/server/Cargo.toml

.github/workflows/publish-hermes-client.yml

@@ -0,0 +1,21 @@
+name: Publish Hermes Client package
+
+on:
+  push:
+    tags:
+      - hermes-client-v*
+jobs:
+  publish-js:
+    name: Publish Hermes Client to NPM
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: "18"
+          registry-url: "https://registry.npmjs.org"
+      - run: npm ci
+      - run: npx lerna run build --no-private
+      - run: npx lerna publish from-git --yes --no-private --no-git-tag-version
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.pre-commit-config.yaml

@@ -50,13 +50,13 @@ repos:
       - id: cargo-fmt-hermes
         name: Cargo format for Hermes
         language: "rust"
-        entry: cargo +nightly-2024-03-26 fmt --manifest-path ./apps/hermes/Cargo.toml --all -- --config-path rustfmt.toml
+        entry: cargo +nightly-2024-03-26 fmt --manifest-path ./apps/hermes/server/Cargo.toml --all -- --config-path rustfmt.toml
         pass_filenames: false
         files: apps/hermes
       - id: cargo-clippy-hermes
         name: Cargo clippy for Hermes
         language: "rust"
-        entry: cargo +nightly-2024-03-26 clippy --manifest-path ./apps/hermes/Cargo.toml --tests --fix --allow-dirty --allow-staged -- -D warnings
+        entry: cargo +nightly-2024-03-26 clippy --manifest-path ./apps/hermes/server/Cargo.toml --tests --fix --allow-dirty --allow-staged -- -D warnings
         pass_filenames: false
         files: apps/hermes
       # Hooks for Fortuna

apps/hermes/client/js/.eslintrc.js

@@ -0,0 +1,6 @@
+module.exports = {
+  root: true,
+  parser: "@typescript-eslint/parser",
+  plugins: ["@typescript-eslint"],
+  extends: ["eslint:recommended", "plugin:@typescript-eslint/recommended"],
+};

apps/hermes/client/js/.gitignore

@@ -0,0 +1 @@
+lib/

apps/hermes/client/js/README.md

@@ -0,0 +1,89 @@
+# Hermes Client
+
+[Pyth Network](https://pyth.network/) provides real-time pricing data in a variety of asset classes, including cryptocurrency, equities, FX and commodities.
+These prices are available either via HTTP or Streaming from [Hermes](/apps/hermes).
+This library is a client for interacting with Hermes, allowing your application to consume Pyth real-time prices in on- and off-chain Javascript/Typescript applications.
+
+## Installation
+
+### npm
+
+```
+$ npm install --save @pythnetwork/hermes-client
+```
+
+### Yarn
+
+```
+$ yarn add @pythnetwork/hermes-client
+```
+
+## Quickstart
+
+Typical usage of the connection is along the following lines:
+
+```typescript
+const connection = new HermesClient("https://hermes.pyth.network", {}); // See Hermes endpoints section below for other endpoints
+
+const priceIds = [
+  // You can find the ids of prices at https://pyth.network/developers/price-feed-ids
+  "0xe62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43", // BTC/USD price id
+  "0xff61491a931112ddf1bd8147cd1b641375f79f5825126d665480874634fd0ace", // ETH/USD price id
+];
+
+// Get price feeds
+const priceFeeds = await connection.getPriceFeeds("btc", "crypto");
+console.log(priceFeeds);
+
+// Latest price updates
+const priceUpdates = await connection.getLatestPriceUpdates(priceIds);
+console.log(priceUpdates);
+```
+
+`HermesClient` also allows subscribing to real-time price updates over a Server-Sent Events (SSE) connection:
+
+```typescript
+// Streaming price updates
+const eventSource = await connection.getStreamingPriceUpdates(priceIds);
+
+eventSource.onmessage = (event) => {
+  console.log("Received price update:", event.data);
+};
+
+eventSource.onerror = (error) => {
+  console.error("Error receiving updates:", error);
+  eventSource.close();
+};
+
+await sleep(5000);
+
+// To stop listening to the updates, you can call eventSource.close();
+console.log("Closing event source.");
+eventSource.close();
+```
+
+### On-chain Applications
+
+On-chain applications will need to submit the price updates returned by Hermes to the Pyth contract on their blockchain.
+By default, these updates are returned as binary data and is serialized as either a base64 string or a hex string depending on the chosen encoding. This binary data will need to be submitted to the Pyth contract.
+
+### Examples
+
+The [HermesClient](./src/examples/HermesClient.ts) example demonstrates both the examples above.
+You can run it with `npm run example`.
+A full command that prints BTC and ETH price feeds, in the testnet network, looks like so:
+
+```bash
+npm run example -- \
+  --endpoint https://hermes.pyth.network \
+  --price-ids \
+    0xe62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43 \
+    0xff61491a931112ddf1bd8147cd1b641375f79f5825126d665480874634fd0ace
+```
+
+## Hermes endpoints
+
+Pyth offers a free public endpoint at [https://hermes.pyth.network](https://hermes.pyth.network). However, it is
+recommended to obtain a private endpoint from one of the Hermes RPC providers for more reliability. You can find more
+information about Hermes RPC providers
+[here](https://docs.pyth.network/documentation/pythnet-price-feeds/hermes#public-endpoint).

apps/hermes/client/js/jest.config.js

@@ -0,0 +1,5 @@
+/** @type {import('ts-jest/dist/types').InitialOptionsTsJest} */
+module.exports = {
+  preset: "ts-jest",
+  testEnvironment: "node",
+};

apps/hermes/client/js/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@pythnetwork/hermes-client",
+  "version": "1.0.0",
+  "description": "Pyth Hermes Client",
+  "author": {
+    "name": "Pyth Data Association"
+  },
+  "homepage": "https://pyth.network",
+  "main": "lib/HermesClient.js",
+  "types": "lib/HermesClient.d.ts",
+  "files": [
+    "lib/**/*"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pyth-network/pyth-crosschain",
+    "directory": "apps/hermes/client/js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "jest --testPathIgnorePatterns=.*.e2e.test.ts --passWithNoTests",
+    "test:e2e": "jest --testPathPattern=.*.e2e.test.ts",
+    "build": "tsc",
+    "generate-hermes-api-types": "openapi-zod-client https://hermes.pyth.network/docs/openapi.json --output src/zodSchemas.ts && prettier --write src/zodSchemas.ts",
+    "check-hermes-api-types": "git diff --exit-code src/zodSchemas.ts",
+    "example": "npm run build && node lib/examples/HermesClient.js",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "lint": "eslint src/",
+    "prepublishOnly": "npm run build && npm test && npm run lint",
+    "preversion": "npm run lint",
+    "version": "npm run format && git add -A src"
+  },
+  "keywords": [
+    "pyth",
+    "oracle"
+  ],
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/eventsource": "^1.1.15",
+    "@types/jest": "^29.4.0",
+    "@types/yargs": "^17.0.10",
+    "@typescript-eslint/eslint-plugin": "^5.21.0",
+    "@typescript-eslint/parser": "^5.21.0",
+    "eslint": "^8.14.0",
+    "jest": "^29.4.0",
+    "openapi-zod-client": "^1.18.1",
+    "prettier": "^2.6.2",
+    "ts-jest": "^29.0.5",
+    "typescript": "^4.6.3",
+    "yargs": "^17.4.1"
+  },
+  "dependencies": {
+    "eventsource": "^2.0.2",
+    "zod": "^3.23.8"
+  }
+}