Feature/add fetchPowerUsers and update existing methods

neynarxyz · Mar 30, 2024 · c0c82d7 · c0c82d7
2 parents ec91dce + 6d4cded
commit c0c82d7
Show file tree

Hide file tree

Showing 15 changed files with 296 additions and 91 deletions.
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@neynar/nodejs-sdk",
-  "version": "1.13.1",
+  "version": "1.14.0",
   "description": "SDK to interact with Neynar APIs (https://docs.neynar.com/)",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",

diff --git a/src/neynar-api/common/constants.ts b/src/neynar-api/common/constants.ts
@@ -52,3 +52,8 @@ export enum BulkCastsSortType {
   REPLIES = "replies",
   RECENT = "recent",
 }
+
+export enum BulkUserAddressTypes {
+  CUSTODY_ADDRESS = "custody_address",
+  VERIFIED_ADDRESS = "verified_address"
+}
diff --git a/src/neynar-api/index.ts b/src/neynar-api/index.ts
@@ -8,4 +8,8 @@ export {
   ReactionType,
   FrameButtonActionType
 } from "./v2";
-export { TimeWindow, BulkCastsSortType } from "./common/constants";
+export {
+  TimeWindow,
+  BulkCastsSortType,
+  BulkUserAddressTypes,
+} from "./common/constants";
diff --git a/src/neynar-api/neynar-api-client.ts b/src/neynar-api/neynar-api-client.ts
@@ -30,7 +30,7 @@ import {
   BulkCastsResponse,
   FnameAvailabilityResponse,
   FrameAction,
-  FrameActionResponse,
+  Frame,
   ValidateFrameActionResponse,
   UsersResponse,
   UsersActiveChannelsResponse,
@@ -76,6 +76,7 @@ import { SignedKeyRequestMetadataABI } from "./abi/signed-key-request-metadata";
 import { keyGatewayAbi } from "./abi/key-gateway";
 import {
   BulkCastsSortType,
+  BulkUserAddressTypes,
   SIGNED_KEY_REQUEST_TYPE,
   SIGNED_KEY_REQUEST_TYPE_FOR_ADD_FOR,
   SIGNED_KEY_REQUEST_VALIDATOR,
@@ -949,6 +950,33 @@ export class NeynarAPIClient {
     );
   }
 
+  /**
+   * Fetches a list of "power users" based on Warpcast power badges. This method retrieves users who have been awarded power badges, indicating their significant contribution or influence within the platform.
+   *
+   * @param {Object} [options] - Optional parameters to tailor the request.
+   *   @param {number} [options.limit=25] - The number of power user details to fetch per request. Defaults to a reasonable number with a maximum allowable value of 100. This parameter controls the size of the response, allowing the client to manage data volume and API load.
+   *   @param {string} [options.cursor] - Pagination cursor for the next set of results.
+   *    Omit this parameter for the initial request to start from the beginning of the list.
+   *
+   *  @returns {Promise<UsersResponse>} A promise that resolves to a list of power users, each possibly containing detailed information such as user profiles, contribution metrics, and power badges.
+   *
+   * @example
+   * Usage Example:
+   * ---------------
+   * // Fetch the initial set of power users with a custom limit
+   * client.fetchPowerUsers({ limit: 50 })
+   *   .then(response => console.log(response))
+   *   .catch(error => console.error(error));
+   *
+   *  For more information, refer to the [Farcaster documentation](https://docs.neynar.com/reference/power-users).
+   */
+  public async fetchPowerUsers(options?: {
+    limit?: number;
+    cursor?: string;
+  }): Promise<UsersResponse> {
+    return await this.clients.v2.fetchPowerUsers(options);
+  }
+
   /**
    * Retrieves a list of active users, where "active" is determined by the Warpcast active algorithm.
    * The information about active users is updated every 12 hours. This method is ideal for identifying
@@ -1168,23 +1196,38 @@ export class NeynarAPIClient {
    * per request.
    *
    * @param {Array<string>} addresses - An array of Ethereum addresses.
-   * @returns {Promise<{[key: string]: UserV2[]}>} A promise that resolves to an object where each key
+   * @param {Object} [options] - Optional parameters for the function.
+   * @param {BulkUserAddressTypes[]} [options.addressTypes] - An array of address types to filter the users by. Can include 'custody_address', 'verified_address'. If not specified, both address types are considered.
+   *  Possible values: 'custody_address', 'verified_address'.
+   *
+   * @returns {Promise<{[key: string]: User[]}>} A promise that resolves to an object where each key
    *   is an Ethereum address and the value is an array of `User` objects associated with that address.
    *
    * @throws {Error} If the number of provided addresses exceeds the allowed limit of 350.
    *
    * @example
    * // Example: Fetch users associated with multiple Ethereum addresses
-   * client.fetchBulkUsersByEthereumAddress(['0xa6a8736f18f383f1cc2d938576933e5ea7df01a1','0x7cac817861e5c3384753403fb6c0c556c204b1ce']).then(response => {
+   *
+   * import { BulkUserAddressTypes } from "@neynar/nodejs-sdk";
+   *
+   * client.fetchBulkUsersByEthereumAddress(['0xa6a8736f18f383f1cc2d938576933e5ea7df01a1','0x7cac817861e5c3384753403fb6c0c556c204b1ce'], {addressTypes:[BulkUserAddressTypes.CUSTODY_ADDRESS]}).then(response => {
    *   console.log('Users by Ethereum Addresses:', response);
    * });
    *
    * For more information, refer to the [Neynar documentation](https://docs.neynar.com/reference/user-bulk-by-address).
    */
-  public async fetchBulkUsersByEthereumAddress(addresses: string[]): Promise<{
+  public async fetchBulkUsersByEthereumAddress(
+    addresses: string[],
+    options?: {
+      addressTypes?: BulkUserAddressTypes[];
+    }
+  ): Promise<{
     [key: string]: UserV2[];
   }> {
-    return await this.clients.v2.fetchBulkUsersByEthereumAddress(addresses);
+    return await this.clients.v2.fetchBulkUsersByEthereumAddress(
+      addresses,
+      options
+    );
   }
 
   /**
@@ -1920,6 +1963,10 @@ export class NeynarAPIClient {
    *
    * @param {'1d' | '7d' | '30d'} [timeWindow] - The time window for trending analysis. Options are '1d' (one day),
    *   '7d' (seven days), or '30d' (thirty days).
+   * @param {Object} [options] - Optional parameters to tailor the request.
+   * @param {number} [options.limit=25] - The number of channel details to fetch per request. Defaults to 25, with a maximum allowable value of 100.
+   * @param {string} [options.cursor] - Pagination cursor for the next set of results.
+   *  Omit this parameter for the initial request to start from the first page.
    *
    * @returns {Promise<ChannelListResponse>} A promise that resolves to a `ChannelListResponse` object,
    *   containing a list of trending channels based on the specified time window.
@@ -1928,16 +1975,20 @@ export class NeynarAPIClient {
    * // Example: Retrieve trending channels over the past week
    * import { TimeWindow } from '@neynar/nodejs-sdk'
    *
-   * client.fetchTrendingChannels(TimeWindow.SEVEN_DAYS).then(response => {
+   * client.fetchTrendingChannels(TimeWindow.SEVEN_DAYS, { limit: 20 }).then(response => {
    *   console.log('Trending Channels:', response);
    * });
    *
    * For more information, refer to the [Neynar documentation](https://docs.neynar.com/reference/trending-channels).
    */
   public async fetchTrendingChannels(
-    timeWindow?: TimeWindow
+    timeWindow?: TimeWindow,
+    options?: {
+      limit?: number;
+      cursor?: string;
+    }
   ): Promise<ChannelListResponse> {
-    return await this.clients.v2.fetchTrendingChannels(timeWindow);
+    return await this.clients.v2.fetchTrendingChannels(timeWindow, options);
   }
 
   /**
@@ -2224,7 +2275,7 @@ export class NeynarAPIClient {
    * @param {string} castHash - The hash of the cast on which the action is being performed.
    * @param {FrameAction} action - The specific frame action to be posted.
    *
-   * @returns {Promise<FrameActionResponse>} A promise that resolves to a `FrameActionResponse` object,
+   * @returns {Promise<Frame>} A promise that resolves to a `Frame` object,
    *   indicating the success or failure of the frame action post.
    *
    * @example
@@ -2249,7 +2300,7 @@ export class NeynarAPIClient {
     signerUuid: string,
     castHash: string,
     action: FrameAction
-  ): Promise<FrameActionResponse> {
+  ): Promise<Frame> {
     return await this.clients.v2.postFrameAction(signerUuid, castHash, action);
   }
 

diff --git a/src/neynar-api/v2/client.ts b/src/neynar-api/v2/client.ts
@@ -67,6 +67,7 @@ import type { SetRequired } from "type-fest";
 import { NFTApi, RelevantMints } from "./openapi-recommendation";
 import {
   BulkCastsSortType,
+  BulkUserAddressTypes,
   TimeWindow,
   TrendingFeedTimeWindow,
 } from "../common/constants";
@@ -440,6 +441,38 @@ export class NeynarV2APIClient {
     return response.data;
   }
 
+  /**
+   * Fetches a list of "power users" based on Warpcast power badges. This method retrieves users who have been awarded power badges, indicating their significant contribution or influence within the platform.
+   *
+   * @param {Object} [options] - Optional parameters to tailor the request.
+   *   @param {number} [options.limit=25] - The number of power user details to fetch per request. Defaults to a reasonable number with a maximum allowable value of 100. This parameter controls the size of the response, allowing the client to manage data volume and API load.
+   *   @param {string} [options.cursor] - Pagination cursor for the next set of results.
+   *    Omit this parameter for the initial request to start from the beginning of the list.
+   *
+   *  @returns {Promise<UsersResponse>} A promise that resolves to a list of power users, each possibly containing detailed information such as user profiles, contribution metrics, and power badges.
+   *
+   * @example
+   * Usage Example:
+   * ---------------
+   * // Fetch the initial set of power users with a custom limit
+   * client.fetchPowerUsers({ limit: 50 })
+   *   .then(response => console.log(response))
+   *   .catch(error => console.error(error));
+   *
+   *  For more information, refer to the [Farcaster documentation](https://docs.neynar.com/reference/power-users).
+   */
+  public async fetchPowerUsers(options?: {
+    limit?: number;
+    cursor?: string;
+  }): Promise<UsersResponse> {
+    const response = await this.apis.user.powerUsers(
+      this.apiKey,
+      options?.limit,
+      options?.cursor
+    );
+    return response.data;
+  }
+
   /**
    * Retrieves a list of active users, where "active" is determined by the Warpcast active algorithm.
    * The information about active users is updated every 12 hours. This method is ideal for identifying
@@ -716,28 +749,43 @@ export class NeynarV2APIClient {
    * per request.
    *
    * @param {Array<string>} addresses - An array of Ethereum addresses.
+   * @param {Object} [options] - Optional parameters for the function.
+   * @param {BulkUserAddressTypes[]} [options.addressTypes] - An array of address types to filter the users by. Can include 'custody_address', 'verified_address'. If not specified, both address types are considered.
+   *  Possible values: 'custody_address', 'verified_address'.
+   *
    * @returns {Promise<{[key: string]: User[]}>} A promise that resolves to an object where each key
    *   is an Ethereum address and the value is an array of `User` objects associated with that address.
    *
    * @throws {Error} If the number of provided addresses exceeds the allowed limit of 350.
    *
    * @example
    * // Example: Fetch users associated with multiple Ethereum addresses
-   * client.fetchBulkUsersByEthereumAddress(['0xa6a8736f18f383f1cc2d938576933e5ea7df01a1','0x7cac817861e5c3384753403fb6c0c556c204b1ce']).then(response => {
+   *
+   * import { BulkUserAddressTypes } from "@neynar/nodejs-sdk";
+   *
+   * client.fetchBulkUsersByEthereumAddress(['0xa6a8736f18f383f1cc2d938576933e5ea7df01a1','0x7cac817861e5c3384753403fb6c0c556c204b1ce'], {addressTypes:[BulkUserAddressTypes.CUSTODY_ADDRESS]}).then(response => {
    *   console.log('Users by Ethereum Addresses:', response);
    * });
    *
    * For more information, refer to the [Neynar documentation](https://docs.neynar.com/reference/user-bulk-by-address).
    */
-  public async fetchBulkUsersByEthereumAddress(addresses: string[]): Promise<{
+  public async fetchBulkUsersByEthereumAddress(
+    addresses: string[],
+    options?: {
+      addressTypes?: BulkUserAddressTypes[];
+    }
+  ): Promise<{
     [key: string]: User[];
   }> {
     if (addresses.length > 350)
       throw new Error("Maximum number of addresses allowed is 350");
     const _addresses = addresses.join(",");
+    const _addressTypes =
+      options?.addressTypes && options?.addressTypes.join(",");
     const response = await this.apis.user.userBulkByAddress(
       this.apiKey,
-      _addresses
+      _addresses,
+      _addressTypes
     );
     return response.data;
   }
@@ -1645,6 +1693,10 @@ export class NeynarV2APIClient {
    *
    * @param {'1d' | '7d' | '30d'} [timeWindow] - The time window for trending analysis. Options are '1d' (one day),
    *   '7d' (seven days), or '30d' (thirty days).
+   * @param {Object} [options] - Optional parameters to tailor the request.
+   * @param {number} [options.limit=25] - The number of channel details to fetch per request. Defaults to 25, with a maximum allowable value of 100.
+   * @param {string} [options.cursor] - Pagination cursor for the next set of results.
+   *  Omit this parameter for the initial request to start from the first page.
    *
    * @returns {Promise<ChannelListResponse>} A promise that resolves to a `ChannelListResponse` object,
    *   containing a list of trending channels based on the specified time window.
@@ -1653,18 +1705,24 @@ export class NeynarV2APIClient {
    * // Example: Retrieve trending channels over the past week
    * import { TimeWindow } from '@neynar/nodejs-sdk'
    *
-   * client.fetchTrendingChannels(TimeWindow.SEVEN_DAYS).then(response => {
+   * client.fetchTrendingChannels(TimeWindow.SEVEN_DAYS, { limit: 20 }).then(response => {
    *   console.log('Trending Channels:', response);
    * });
    *
    * For more information, refer to the [Neynar documentation](https://docs.neynar.com/reference/trending-channels).
    */
   public async fetchTrendingChannels(
-    timeWindow?: TimeWindow
+    timeWindow?: TimeWindow,
+    options?: {
+      limit?: number;
+      cursor?: string;
+    }
   ): Promise<ChannelListResponse> {
     const response = await this.apis.channel.trendingChannels(
       this.apiKey,
-      timeWindow
+      timeWindow,
+      options?.limit,
+      options?.cursor
     );
     return response.data;
   }
@@ -1963,7 +2021,7 @@ export class NeynarV2APIClient {
    * @param {string} castHash - The hash of the cast on which the action is being performed.
    * @param {FrameAction} action - The specific frame action to be posted.
    *
-   * @returns {Promise<FrameActionResponse>} A promise that resolves to a `FrameActionResponse` object,
+   * @returns {Promise<Frame>} A promise that resolves to a `Frame` object,
    *   indicating the success or failure of the frame action post.
    *
    * @example

diff --git a/src/neynar-api/v2/openapi-farcaster/.openapi-generator/FILES b/src/neynar-api/v2/openapi-farcaster/.openapi-generator/FILES
@@ -61,7 +61,6 @@ models/follow-response.ts
 models/follow.ts
 models/frame-action-button.ts
 models/frame-action-req-body.ts
-models/frame-action-response.ts
 models/frame-action.ts
 models/frame-button-action-type.ts
 models/frame-input.ts