Merge pull request #1762 from cprussin/api-reference-improvements

Implement API reference feedback

Author: cprussin

apps/api-reference/.gitignore

@@ -0,0 +1 @@
+.env*.local

apps/api-reference/next.config.js

@@ -1,6 +1,4 @@
-import withMDX from "@next/mdx";
-
-const config = {
+export default {
   reactStrictMode: true,
 
   pageExtensions: ["ts", "tsx", "mdx"],
@@ -24,7 +22,7 @@ const config = {
     return config;
   },
 
-  transpilePackages: ["@pyth.network/*"],
+  transpilePackages: ["@pythnetwork/*"],
 
   headers: () => [
     {
@@ -55,5 +53,3 @@ const config = {
     },
   ],
 };
-
-export default withMDX()(config);

apps/api-reference/package.json

@@ -11,6 +11,7 @@
     "fix": "pnpm fix:format && pnpm fix:lint",
     "fix:format": "prettier --write .",
     "fix:lint": "eslint --fix .",
+    "pull:env": "VERCEL_ORG_ID=team_BKQrg3JJFLxZyTqpuYtIY0rj VERCEL_PROJECT_ID=prj_gbljYVzp0m5EpCuOF6nZpM4WMFM6 vercel env pull",
     "start:dev": "next dev",
     "start:prod": "next start",
     "test": "tsc && jest",
@@ -21,13 +22,10 @@
   },
   "dependencies": {
     "@amplitude/analytics-browser": "^2.9.0",
+    "@amplitude/plugin-autocapture-browser": "^0.9.0",
     "@floating-ui/react": "^0.26.17",
     "@headlessui/react": "^2.0.4",
     "@heroicons/react": "^2.1.4",
-    "@mdx-js/loader": "^3.0.1",
-    "@mdx-js/mdx": "^3.0.1",
-    "@mdx-js/react": "^3.0.1",
-    "@next/mdx": "^14.2.4",
     "@next/third-parties": "^14.2.4",
     "@pythnetwork/pyth-sdk-solidity": "workspace:^",
     "@tanstack/react-query": "^5.45.1",
@@ -39,6 +37,7 @@
     "pino": "^9.2.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
+    "react-markdown": "^9.0.1",
     "shiki": "^1.7.0",
     "viem": "^2.15.1",
     "wagmi": "^2.10.4",
@@ -53,7 +52,6 @@
     "@svgr/webpack": "^8.1.0",
     "@tailwindcss/forms": "^0.5.7",
     "@types/jest": "^29.5.12",
-    "@types/mdx": "^2.0.13",
     "@types/node": "^20.14.6",
     "@types/react": "^18.3.3",
     "@types/react-dom": "^18.3.0",

apps/api-reference/public/.well-known/walletconnect.txt

@@ -0,0 +1 @@
+6486ae45-385f-4747-b8b5-885380fb4ec8=57ef2db8537f4094003f355e80ee6a28a072d4b95baba68db01bac4981ea0f1b

apps/api-reference/src/apis/evm/common.ts

@@ -10,18 +10,14 @@ import {
 import { singletonArray, safeFetch } from "../../zod-utils";
 
 export const readApi = <ParameterName extends string>(
-  spec: Omit<ReadApi<ParameterName>, "children" | "type"> & {
-    description: string;
-  },
+  spec: Omit<ReadApi<ParameterName>, "type">,
 ) => ({
   ...spec,
   type: EvmApiType.Read,
 });
 
 export const writeApi = <ParameterName extends string>(
-  spec: Omit<WriteApi<ParameterName>, "children" | "type"> & {
-    description: string;
-  },
+  spec: Omit<WriteApi<ParameterName>, "type">,
 ) => ({
   ...spec,
   type: EvmApiType.Write,
@@ -34,19 +30,15 @@ export const ETHUSD =
 
 const HERMES_URL = "https://hermes.pyth.network";
 
-export const getLatestPriceFeed = async (feedId: string) => {
+export const getLatestPriceUpdate = async (feedId: string) => {
   const url = new URL("/v2/updates/price/latest", HERMES_URL);
   url.searchParams.set("ids[]", feedId);
-  url.searchParams.set("target_chain", "evm");
-  url.searchParams.set("binary", "true");
   return safeFetch(priceFeedSchema, url);
 };
 
 const priceFeedSchema = z.object({
   binary: z.object({
-    data: singletonArray(z.string()).transform((value) =>
-      toZeroXPrefixedHex(value),
-    ),
+    data: singletonArray(z.string()).transform((value) => `0x${value}`),
   }),
   parsed: singletonArray(
     z.object({
@@ -57,9 +49,6 @@ const priceFeedSchema = z.object({
   ),
 });
 
-const toZeroXPrefixedHex = (value: string) =>
-  `0x${Buffer.from(value, "base64").toString("hex")}`;
-
 export const solidity = <ParameterName extends string>(
   code: string | ((params: Partial<Record<ParameterName, string>>) => string),
 ) => ({

apps/api-reference/src/apis/evm/get-ema-price-no-older-than.ts

@@ -6,6 +6,8 @@ import { ParameterType } from "../../components/EvmApi";
 
 export const getEmaPriceNoOlderThan = readApi<"id" | "age">({
   name: "getEmaPriceNoOlderThan",
+  summary:
+    "Get the exponentially weighted moving average (EMA) price object with a published timestamp from before than `age` seconds in the past.",
   description: `
 Get the latest exponentially-weighted moving average (EMA) price and confidence
 interval for the requested price feed id.  The price feed id is a 32-byte id

apps/api-reference/src/apis/evm/get-ema-price-unsafe.ts

@@ -6,6 +6,8 @@ import { ParameterType } from "../../components/EvmApi";
 
 export const getEmaPriceUnsafe = readApi<"id">({
   name: "getEmaPriceUnsafe",
+  summary:
+    "Get the **last updated** exponentially weighted moving average (EMA) price object for the requested price feed ID. _Caution: This function may return a price arbitrarily in the past_",
   description: `
 Get the latest exponentially-weighted moving average (EMA) price and confidence
 interval for the requested price feed id.  The price feed id is a 32-byte id

apps/api-reference/src/apis/evm/get-ema-price.ts

@@ -6,6 +6,8 @@ import { ParameterType } from "../../components/EvmApi";
 
 export const getEmaPrice = readApi<"id">({
   name: "getEmaPrice",
+  summary:
+    "Get the **latest** exponentially weighted moving average (EMA) price object for the requested price feed ID.",
   description: `
 Get the latest exponentially-weighted moving average (EMA) price and confidence
 interval for the requested price feed id.  The price feed id is a 32-byte id

apps/api-reference/src/apis/evm/get-price-no-older-than.ts

@@ -6,6 +6,8 @@ import { ParameterType } from "../../components/EvmApi";
 
 export const getPriceNoOlderThan = readApi<"id" | "age">({
   name: "getPriceNoOlderThan",
+  summary:
+    "Get the price object with a published timestamp from before than `age` seconds in the past.",
   description: `
 Get the latest price and confidence interval for the requested price feed id, if
 it has been updated sufficiently recently.  The price feed id is a 32-byte id

apps/api-reference/src/apis/evm/get-price-unsafe.ts

@@ -6,6 +6,8 @@ import { ParameterType } from "../../components/EvmApi";
 
 export const getPriceUnsafe = readApi<"id">({
   name: "getPriceUnsafe",
+  summary:
+    "Get the **last updated** price object for the requested price feed ID. _Caution: This function may return a price from arbitrarily in the the past_",
   description: `
 Get the latest price and confidence interval for the requested price feed id.
 The price feed id is a 32-byte id written as a hexadecimal string; see the