Add leaderboard and featured creators queries (#1430)

Author: iainnash

.changeset/happy-panthers-invite.md

@@ -0,0 +1,5 @@
+---
+"@zoralabs/coins-sdk": patch
+---
+
+Add new leaderboard and featured creators queries

docs/pages/coins/sdk/queries/explore.mdx

@@ -12,6 +12,8 @@ The Coins SDK provides several explore functions to discover coins based on diff
 - [`getCoinsLastTradedUnique`](#getcoinslasttradedunique)
 - [`getCreatorCoins`](#getcreatorcoins)
 - [`getMostValuableCreatorCoins`](#getmostvaluablecreatorcoins)
+ - [`getMostValuableCreatorCoins`](#getmostvaluablecreatorcoins)
+ 
 
 ## Available Explore Queries
 
@@ -272,6 +274,8 @@ async function fetchMostValuableCreatorCoins() {
   return tokens;
 }
 ```
+
+ 
 
 ## Response Structure
 
@@ -319,7 +323,8 @@ type ListType =
   | "FEATURED"
   | "FEATURED_VIDEOS"
   | "NEW_CREATORS"
-  | "MOST_VALUABLE_CREATORS";
+  | "MOST_VALUABLE_CREATORS"
+  | "FEATURED_CREATORS";
 ```
 
 ## Pagination

docs/pages/coins/sdk/queries/index.mdx

@@ -9,6 +9,7 @@ The query functions are divided into several categories:
 1. **[Coin Queries](/coins/sdk/queries/coin)**: Retrieve information on specific coins such as metadata, market data, and comments
 2. **[Profile Queries](/coins/sdk/queries/profile)**: Retrieve information associated with users/wallets like holdings and activity
 3. **[Explore Queries](/coins/sdk/queries/explore)**: Retrieve information about all coins (new, trending, top gainers, etc.)
+4. **[Leaderboard](/coins/sdk/queries/leaderboard)**: Featured creators and weekly trader leaderboard (defaults to current week/year if not specified)
 
 ## Using the REST API
 

docs/pages/coins/sdk/queries/leaderboard.mdx

@@ -0,0 +1,50 @@
+# Leaderboard Queries
+
+The Coins SDK exposes queries for weekly Featured Creators and the Trader Leaderboard.
+
+- These queries support optional `year` and `week` parameters.
+- Weeks use ISO week numbering (starting at 1).
+- If `year` and `week` are not provided, the current ISO week and year are used.
+- Passing a specific `year` and `week` retrieves data for that week of that year.
+
+## getFeaturedCreators
+
+Retrieves a weekly featured creators list. Supports optional `year`, `week`, and pagination via `first` and `after`.
+
+```ts twoslash
+import { getFeaturedCreators } from "@zoralabs/coins-sdk";
+
+async function fetchFeaturedCreators() {
+  // If year/week not passed, uses the current week/year by default
+  const response = await getFeaturedCreators({
+    year: undefined, // optional
+    week: undefined, // optional
+    first: 10,       // optional: page size
+  });
+
+  return response.data?.traderLeaderboardFeaturedCreators?.edges?.map((e: any) => e.node);
+}
+```
+
+## getTraderLeaderboard
+
+Retrieves the weekly trader leaderboard. Supports optional `year`, `week`, `first`, and `after`.
+
+Passing in a `year` and `week` will return the leaderboard for that specific week of the year. If no year or week is passed in, it will return the current week's leaderboard.
+
+```ts twoslash
+import { getTraderLeaderboard } from "@zoralabs/coins-sdk";
+
+async function fetchTraderLeaderboard() {
+  // Defaults to the current week/year when omitted
+  const response = await getTraderLeaderboard({
+    year: undefined, // optional
+    week: undefined, // optional
+    first: 10,       // optional: page size
+  });
+
+  return response.data?.exploreTraderLeaderboard?.edges?.map((e: any) => e.node);
+}
+```
+
+

docs/vocs.config.ts

@@ -147,6 +147,10 @@ export default defineConfig({
                     text: "Explore Coins",
                     link: "/coins/sdk/queries/explore",
                   },
+                  {
+                    text: "Leaderboard",
+                    link: "/coins/sdk/queries/leaderboard",
+                  },
                 ],
               },
             ],

packages/coins-sdk/src/api/queries.ts

@@ -15,6 +15,10 @@ import {
   GetProfileCoinsResponse,
   GetProfileData,
   GetProfileResponse,
+  GetFeaturedCreatorsData,
+  GetFeaturedCreatorsResponse,
+  GetTraderLeaderboardData,
+  GetTraderLeaderboardResponse,
 } from "../client/types.gen";
 import {
   getCoin as getCoinSDK,
@@ -25,6 +29,8 @@ import {
   getProfile as getProfileSDK,
   getProfileBalances as getProfileBalancesSDK,
   getProfileCoins as getProfileCoinsSDK,
+  getFeaturedCreators as getFeaturedCreatorsSDK,
+  getTraderLeaderboard as getTraderLeaderboardSDK,
 } from "../client/sdk.gen";
 import { getApiKeyMeta } from "./api-key";
 import { RequestOptionsType } from "./query-types";
@@ -155,3 +161,33 @@ export const getProfileBalances = async (
     ...options,
   });
 };
+
+type GetFeaturedCreatorsQuery = GetFeaturedCreatorsData["query"];
+export type { GetFeaturedCreatorsQuery, GetFeaturedCreatorsData };
+export type { GetFeaturedCreatorsResponse } from "../client/types.gen";
+
+export const getFeaturedCreators = async (
+  query: GetFeaturedCreatorsQuery = {},
+  options?: RequestOptionsType<GetFeaturedCreatorsData>,
+): Promise<RequestResult<GetFeaturedCreatorsResponse>> => {
+  return await getFeaturedCreatorsSDK({
+    query,
+    ...getApiKeyMeta(),
+    ...options,
+  });
+};
+
+type GetTraderLeaderboardQuery = GetTraderLeaderboardData["query"];
+export type { GetTraderLeaderboardQuery, GetTraderLeaderboardData };
+export type { GetTraderLeaderboardResponse } from "../client/types.gen";
+
+export const getTraderLeaderboard = async (
+  query: GetTraderLeaderboardQuery = {},
+  options?: RequestOptionsType<GetTraderLeaderboardData>,
+): Promise<RequestResult<GetTraderLeaderboardResponse>> => {
+  return await getTraderLeaderboardSDK({
+    query,
+    ...getApiKeyMeta(),
+    ...options,
+  });
+};

packages/coins-sdk/src/client/sdk.gen.ts

@@ -22,12 +22,18 @@ import type {
   SetCreateUploadJwtResponse,
   GetExploreData,
   GetExploreResponse,
+  GetFeaturedCreatorsData,
+  GetFeaturedCreatorsResponse,
   GetProfileData,
   GetProfileResponse,
   GetProfileBalancesData,
   GetProfileBalancesResponse,
   GetProfileCoinsData,
   GetProfileCoinsResponse,
+  GetTokenInfoData,
+  GetTokenInfoResponse,
+  GetTraderLeaderboardData,
+  GetTraderLeaderboardResponse,
   PostQuoteData,
   PostQuoteResponse,
   PostQuoteError,
@@ -237,6 +243,28 @@ export const getExplore = <ThrowOnError extends boolean = false>(
   });
 };
 
+/**
+ * zoraSDK_featuredCreators query
+ */
+export const getFeaturedCreators = <ThrowOnError extends boolean = false>(
+  options?: Options<GetFeaturedCreatorsData, ThrowOnError>,
+) => {
+  return (options?.client ?? _heyApiClient).get<
+    GetFeaturedCreatorsResponse,
+    unknown,
+    ThrowOnError
+  >({
+    security: [
+      {
+        name: "api-key",
+        type: "apiKey",
+      },
+    ],
+    url: "/featuredCreators",
+    ...options,
+  });
+};
+
 /**
  * zoraSDK_profile query
  */
@@ -303,6 +331,50 @@ export const getProfileCoins = <ThrowOnError extends boolean = false>(
   });
 };
 
+/**
+ * zoraSDK_tokenInfo query
+ */
+export const getTokenInfo = <ThrowOnError extends boolean = false>(
+  options: Options<GetTokenInfoData, ThrowOnError>,
+) => {
+  return (options.client ?? _heyApiClient).get<
+    GetTokenInfoResponse,
+    unknown,
+    ThrowOnError
+  >({
+    security: [
+      {
+        name: "api-key",
+        type: "apiKey",
+      },
+    ],
+    url: "/tokenInfo",
+    ...options,
+  });
+};
+
+/**
+ * zoraSDK_traderLeaderboard query
+ */
+export const getTraderLeaderboard = <ThrowOnError extends boolean = false>(
+  options?: Options<GetTraderLeaderboardData, ThrowOnError>,
+) => {
+  return (options?.client ?? _heyApiClient).get<
+    GetTraderLeaderboardResponse,
+    unknown,
+    ThrowOnError
+  >({
+    security: [
+      {
+        name: "api-key",
+        type: "apiKey",
+      },
+    ],
+    url: "/traderLeaderboard",
+    ...options,
+  });
+};
+
 export const postQuote = <ThrowOnError extends boolean = false>(
   options?: Options<PostQuoteData, ThrowOnError>,
 ) => {