chore(dev-hub) Add API card component

Author: aditya520

apps/developer-hub/content/docs/api-reference/entropy/fortuna/index.mdx

@@ -4,20 +4,23 @@ title: Overview
 
 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
 
-<Cards>
-  <Card
+<APICards>
+  <APICard
     href="/api-reference/entropy/fortuna/chain_ids"
-    title="Get the list of supported chain ids"
+    title="/v1/chains"
+    method="GET"
     description="Get the list of supported chain ids"
   />
-  <Card
+  <APICard
     href="/api-reference/entropy/fortuna/revelation"
-    title="Reveal the random value for a given sequence number and blockchain."
-    description="Reveal the random value for a given sequence number and blockchain.\n\nGiven a sequence number, retrieve the corresponding random value that this provider has committed to.\nThis endpoint will not return the random value unless someone has requested the sequence number on-chain.\n\nEvery blockchain supported by this service has a distinct sequence of random numbers and chain_id.\nCallers must pass the appropriate chain_id to ensure they fetch the correct random number."
+    title="/v1/chains/{chain_id}/revelations/{sequence}"
+    method="GET"
+    description="Reveal the random value for a given sequence number and blockchain."
   />
-  <Card
+  <APICard
     href="/api-reference/entropy/fortuna/explorer"
-    title="Returns the logs of all requests captured by the keeper."
-    description="Returns the logs of all requests captured by the keeper.\n\nThis endpoint allows you to filter the logs by a specific network ID, a query string (which can be a transaction hash, sender address, or sequence number), and a time range.\nThis is useful for debugging and monitoring the requests made to the Entropy contracts on various chains."
+    title="/v1/logs"
+    method="GET"
+    description="Returns the logs of all requests captured by the keeper."
   />
-</Cards>
+</APICards>

apps/developer-hub/content/docs/api-reference/pyth-core/hermes/index.mdx

@@ -4,65 +4,77 @@ title: Overview
 
 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
 
-<Cards>
-  <Card
+<APICards>
+  <APICard
     href="/api-reference/pyth-core/hermes/get_price_feed"
-    title="**Deprecated: use /v2/updates/price/{publish_time} instead**"
-    description="**Deprecated: use /v2/updates/price/{publish_time} instead**\n\nGet a price update for a price feed with a specific timestamp\n\nGiven a price feed id and timestamp, retrieve the Pyth price update closest to that timestamp."
+    title="/api/get_price_feed"
+    method="GET"
+    description="Get a price update for a price feed with a specific timestamp Given a price feed id and timestamp, retrieve the Pyth price update closest to that timestamp."
   />
-  <Card
+  <APICard
     href="/api-reference/pyth-core/hermes/get_vaa"
-    title="**Deprecated: use /v2/updates/price/{publish_time} instead**"
-    description="**Deprecated: use /v2/updates/price/{publish_time} instead**\n\nGet a VAA for a price feed with a specific timestamp\n\nGiven a price feed id and timestamp, retrieve the Pyth price update closest to that timestamp."
+    title="/api/get_vaa"
+    method="GET"
+    description="Get a VAA for a price feed with a specific timestamp Given a price feed id and timestamp, retrieve the Pyth price update closest to that timestamp."
   />
-  <Card
+  <APICard
     href="/api-reference/pyth-core/hermes/get_vaa_ccip"
-    title="**Deprecated: use /v2/updates/price/{publish_time} instead**"
-    description="**Deprecated: use /v2/updates/price/{publish_time} instead**\n\nGet a VAA for a price feed using CCIP\n\nThis endpoint accepts a single argument which is a hex-encoded byte string of the following form:\n`<price feed id (32 bytes> <publish time as unix timestamp (8 bytes, big endian)>`"
+    title="/api/get_vaa_ccip"
+    method="GET"
+    description="Get a VAA for a price feed using CCIP This endpoint accepts a single argument which is a hex-encoded byte string of the following form: `<price feed id (32 bytes> <publish time as unix timestamp (8 bytes, big endian)>`"
   />
-  <Card
+  <APICard
     href="/api-reference/pyth-core/hermes/latest_price_feeds"
-    title="**Deprecated: use /v2/updates/price/latest instead**"
-    description="**Deprecated: use /v2/updates/price/latest instead**\n\nGet the latest price updates by price feed id.\n\nGiven a collection of price feed ids, retrieve the latest Pyth price for each price feed."
+    title="/api/latest_price_feeds"
+    method="GET"
+    description="Get the latest price updates by price feed id."
   />
-  <Card
+  <APICard
     href="/api-reference/pyth-core/hermes/latest_vaas"
-    title="**Deprecated: use /v2/updates/price/latest instead**"
-    description="**Deprecated: use /v2/updates/price/latest instead**\n\nGet VAAs for a set of price feed ids.\n\nGiven a collection of price feed ids, retrieve the latest VAA for each. The returned VAA(s) can\nbe submitted to the Pyth contract to update the on-chain price. If VAAs are not found for every\nprovided price ID the call will fail."
+    title="/api/latest_vaas"
+    method="GET"
+    description="Get VAAs for a set of price feed ids."
   />
-  <Card
+  <APICard
     href="/api-reference/pyth-core/hermes/price_feed_ids"
-    title="**Deprecated: use /v2/price_feeds instead**"
-    description="**Deprecated: use /v2/price_feeds instead**\n\nGet the set of price feed IDs.\n\nThis endpoint fetches all of the price feed IDs for which price updates can be retrieved."
+    title="/api/price_feed_ids"
+    method="GET"
+    description="Get the set of price feed IDs."
   />
-  <Card
+  <APICard
     href="/api-reference/pyth-core/hermes/price_feeds_metadata"
-    title="Get the set of price feeds."
-    description="Get the set of price feeds.\n\nThis endpoint fetches all price feeds from the Pyth network. It can be filtered by asset type\nand query string."
+    title="/v2/price_feeds"
+    method="GET"
+    description="Get the set of price feeds."
   />
-  <Card
+  <APICard
     href="/api-reference/pyth-core/hermes/latest_price_updates"
-    title="Get the latest price updates by price feed id."
-    description="Get the latest price updates by price feed id.\n\nGiven a collection of price feed ids, retrieve the latest Pyth price for each price feed."
+    title="/v2/updates/price/latest"
+    method="GET"
+    description="Get the latest price updates by price feed id."
   />
-  <Card
+  <APICard
     href="/api-reference/pyth-core/hermes/price_stream_sse_handler"
-    title="SSE route handler for streaming price updates."
-    description="SSE route handler for streaming price updates.\n\nThe connection will automatically close after 24 hours to prevent resource leaks.\nClients should implement reconnection logic to maintain continuous price updates."
+    title="/v2/updates/price/stream"
+    method="GET"
+    description="SSE route handler for streaming price updates."
   />
-  <Card
+  <APICard
     href="/api-reference/pyth-core/hermes/timestamp_price_updates"
-    title="Get the latest price updates by price feed id."
-    description="Get the latest price updates by price feed id.\n\nGiven a collection of price feed ids, retrieve the latest Pyth price for each price feed."
+    title="/v2/updates/price/{publish_time}"
+    method="GET"
+    description="Get the latest price updates by price feed id."
   />
-  <Card
+  <APICard
     href="/api-reference/pyth-core/hermes/latest_publisher_stake_caps"
-    title="Get the most recent publisher stake caps update data."
+    title="/v2/updates/publisher_stake_caps/latest"
+    method="GET"
     description="Get the most recent publisher stake caps update data."
   />
-  <Card
+  <APICard
     href="/api-reference/pyth-core/hermes/latest_twaps"
-    title="Get the latest TWAP by price feed id with a custom time window."
-    description="Get the latest TWAP by price feed id with a custom time window.\n\nGiven a collection of price feed ids, retrieve the latest Pyth TWAP price for each price feed."
+    title="/v2/updates/twap/{window_seconds}/latest"
+    method="GET"
+    description="Get the latest TWAP by price feed id with a custom time window."
   />
-</Cards>
+</APICards>

apps/developer-hub/scripts/generate-docs.ts

@@ -76,6 +76,9 @@ export async function generateDocs() {
 
   // Post-process MDX files to use endpoint paths as titles
   await updateMdxTitles();
+
+  // Rewrite index cards to use path as title and first sentence as description
+  await updateIndexCards();
 }
 
 async function generateMetaFiles() {
@@ -186,4 +189,126 @@ async function updateMdxTitles(): Promise<void> {
   }
 }
 
+async function updateIndexCards(): Promise<void> {
+  // eslint-disable-next-line no-console
+  console.log(
+    "\nUpdating index cards to use path titles + first-sentence descriptions...",
+  );
+
+  for (const [serviceName, config] of Object.entries(products)) {
+    const serviceDir = path.join(outDir, config.product, serviceName);
+    const indexPath = path.join(serviceDir, "index.mdx");
+
+    try {
+      await fs.access(indexPath);
+    } catch {
+      continue;
+    }
+
+    // Read all endpoint MDX files to extract route, method, and description
+    const endpoints = generatedEndpoints[serviceName] ?? [];
+    const cardData: {
+      href: string;
+      route: string;
+      method: string;
+      description: string;
+    }[] = [];
+
+    for (const operationId of endpoints) {
+      const mdxPath = path.join(serviceDir, `${operationId}.mdx`);
+      try {
+        const content = await fs.readFile(mdxPath, "utf8");
+
+        // Extract route
+        const routeMatch = /route:\s*([^\n]+)/.exec(content);
+        const route = routeMatch?.[1]?.trim() ?? operationId;
+
+        // Extract method
+        const methodMatch = /method:\s*([^\n]+)/.exec(content);
+        const method = methodMatch?.[1]?.trim().toUpperCase() ?? "GET";
+
+        // Extract description (handle both single-line and multiline formats)
+        let descText = "";
+
+        // Try multiline format first: description: >-\n  text
+        const multilineMatch = /description:\s*>-\s*\n((?:\s{2}.*\n)+)/.exec(
+          content,
+        );
+        if (multilineMatch?.[1]) {
+          descText = multilineMatch[1]
+            .split("\n")
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .join(" ");
+        } else {
+          // Try single-line format: description: text
+          const singleMatch = /description:\s*([^\n]+)/.exec(content);
+          if (singleMatch?.[1]) {
+            descText = singleMatch[1].trim();
+          }
+        }
+
+        const firstSentence = getFirstSentence(descText);
+
+        cardData.push({
+          href: `/api-reference/${config.product}/${serviceName}/${operationId}`,
+          route,
+          method,
+          description: firstSentence,
+        });
+      } catch {
+        // Skip if file doesn't exist
+      }
+    }
+
+    // Build new index content with APICards grid and APICard components
+    const cards = cardData
+      .map(
+        (card) =>
+          `  <APICard href="${card.href}" title="${escapeQuotes(card.route)}" method="${card.method}" description="${escapeQuotes(card.description)}" />`,
+      )
+      .join("\n");
+
+    const newIndex = `---
+title: Overview
+---
+
+{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
+
+<APICards>
+${cards}
+</APICards>
+`;
+
+    await fs.writeFile(indexPath, newIndex);
+    // eslint-disable-next-line no-console
+    console.log(
+      `  - Updated index: ${config.product}/${serviceName}/index.mdx`,
+    );
+  }
+}
+
+function getFirstSentence(text: string): string {
+  if (!text) return "";
+
+  // Remove markdown formatting (bold, italic, etc.)
+  let cleaned = text.replaceAll(/\*\*[^*]+\*\*/g, "").trim();
+
+  // If text starts with "Deprecated..." or similar, skip to the actual description
+  if (cleaned.toLowerCase().startsWith("deprecated")) {
+    const afterDeprecated = cleaned.indexOf(")");
+    if (afterDeprecated > 0) {
+      cleaned = cleaned.slice(afterDeprecated + 1).trim();
+    }
+  }
+
+  const sentenceEnd = cleaned.search(/[.!?](\s|$)/);
+  if (sentenceEnd === -1) return cleaned.trim();
+  return cleaned.slice(0, sentenceEnd + 1).trim();
+}
+
+function escapeQuotes(text: string): string {
+  return text.replaceAll('"', String.raw`\"`);
+}
+
 await generateDocs();

apps/developer-hub/src/components/APICard/index.module.scss

@@ -0,0 +1,77 @@
+@use "@pythnetwork/component-library/theme";
+
+.grid {
+  display: grid;
+  grid-template-columns: repeat(2, 1fr);
+  gap: theme.spacing(4);
+
+  @include theme.breakpoint("md") {
+    grid-template-columns: repeat(2, 1fr);
+  }
+
+  @media (width <= 768px) {
+    grid-template-columns: 1fr;
+  }
+}
+
+.card {
+  display: flex;
+  flex-direction: column;
+  gap: theme.spacing(2);
+  padding: theme.spacing(5);
+  border-radius: theme.border-radius("lg");
+  background-color: theme.color("background", "secondary");
+  text-decoration: none;
+  transition: background-color 200ms ease-out;
+
+  &:hover {
+    background-color: theme.color("background", "card-highlight");
+  }
+}
+
+.title {
+  display: flex;
+  align-items: center;
+  gap: theme.spacing(2);
+  flex-wrap: wrap;
+}
+
+.name {
+  font-size: theme.font-size("sm");
+  font-weight: theme.font-weight("semibold");
+  color: theme.color("foreground");
+}
+
+.badge {
+  font-size: theme.font-size("xxs");
+  font-weight: theme.font-weight("semibold");
+  text-transform: uppercase;
+  letter-spacing: theme.letter-spacing("wide");
+}
+
+.get {
+  color: theme.pallette-color("green", 400);
+}
+
+.post {
+  color: theme.pallette-color("amber", 400);
+}
+
+.put {
+  color: theme.pallette-color("blue", 400);
+}
+
+.patch {
+  color: theme.pallette-color("purple", 400);
+}
+
+.delete {
+  color: theme.pallette-color("red", 400);
+}
+
+.description {
+  font-size: theme.font-size("sm");
+  font-weight: theme.font-weight("normal");
+  line-height: 1.6;
+  color: theme.color("muted");
+}