06 22 include count (#343)

* add refreshCache

* add changelog

* add jsdoc

* includeCount

* test

* changelog

* move changelog, update comment

CHANGELOG.md

@@ -6,6 +6,9 @@
 
 ### Minor Changes
 
+- Add the `refreshCache` parameter to NFT rarity endpoints to allow users to update stale rarity values.
+- Add the `includeCount` parameter to getOwnersForContract.
+
 ## 2.9.0
 
 ### Major Changes

src/api/nft-namespace.ts

@@ -520,12 +520,14 @@ export class NftNamespace {
    *
    * @param contractAddress - Contract address for the NFT collection.
    * @param tokenId - Token id of the NFT.
+   * @param refreshCache - If true, bypass cache and recompute rarity snapshot.
    */
   computeRarity(
     contractAddress: string,
-    tokenId: BigNumberish
+    tokenId: BigNumberish,
+    refreshCache?: boolean
   ): Promise<NftAttributeRarity[]> {
-    return computeRarity(this.config, contractAddress, tokenId);
+    return computeRarity(this.config, contractAddress, tokenId, refreshCache);
   }
 
   /**
@@ -541,11 +543,13 @@ export class NftNamespace {
    * Get a summary of attribute prevalence for an NFT collection.
    *
    * @param contractAddress - Contract address for the NFT collection.
+   * @param refreshCache - If true, bypass cache and recompute rarity snapshot.
    */
   summarizeNftAttributes(
-    contractAddress: string
+    contractAddress: string,
+    refreshCache?: boolean
   ): Promise<NftAttributesResponse> {
-    return summarizeNftAttributes(this.config, contractAddress);
+    return summarizeNftAttributes(this.config, contractAddress, refreshCache);
   }
 
   /**

src/internal/nft-api.ts

@@ -307,6 +307,7 @@ export async function getOwnersForContract(
 
   return {
     owners: response.ownerAddresses,
+    totalCount: response.totalCount,
 
     // Only include the pageKey in the final response if it's defined
     ...(response.pageKey !== undefined && { pageKey: response.pageKey })
@@ -623,14 +624,16 @@ export async function computeRarity(
   config: AlchemyConfig,
   contractAddress: string,
   tokenId: BigNumberish,
+  refreshCache?: boolean,
   srcMethod = 'computeRarity'
 ): Promise<NftAttributeRarity[]> {
   const response = await requestHttpWithBackoff<
     ComputeRarityParams,
     RawNftAttributeRarity[]
   >(config, AlchemyApiType.NFT, 'computeRarity', srcMethod, {
     contractAddress,
-    tokenId: BigNumber.from(tokenId).toString()
+    tokenId: BigNumber.from(tokenId).toString(),
+    refreshCache
   });
 
   return getNftRarityFromRaw(response);
@@ -654,13 +657,15 @@ export async function searchContractMetadata(
 export async function summarizeNftAttributes(
   config: AlchemyConfig,
   contractAddress: string,
+  refreshCache?: boolean,
   srcMethod = 'summarizeNftAttributes'
 ): Promise<NftAttributesResponse> {
   return requestHttpWithBackoff<
     SummarizeNftAttributesParams,
     NftAttributesResponse
   >(config, AlchemyApiType.NFT, 'summarizeNftAttributes', srcMethod, {
-    contractAddress
+    contractAddress,
+    refreshCache
   });
 }
 
@@ -1034,6 +1039,7 @@ interface GetNftSalesParams {
 interface ComputeRarityParams {
   contractAddress: string;
   tokenId: string;
+  refreshCache?: boolean;
 }
 
 /**
@@ -1052,6 +1058,7 @@ interface SearchContractMetadataParams {
  */
 interface SummarizeNftAttributesParams {
   contractAddress: string;
+  refreshCache?: boolean;
 }
 
 interface ReingestContractParams {

src/internal/raw-interfaces.ts

@@ -213,6 +213,7 @@ export interface RawContractBaseNft {
  */
 export interface RawGetOwnersForContractResponse {
   ownerAddresses: string[];
+  totalCount?: number;
 }
 
 export interface RawGetOwnersForContractWithTokenBalancesResponse {

src/types/types.ts

@@ -851,6 +851,11 @@ export interface GetOwnersForNftResponse {
 export interface GetOwnersForContractResponse {
   /** An array of owner addresses for the provided contract address */
   owners: string[];
+
+  /**
+   * Total count of unique owners. Only present if
+   * {@link GetOwnersForContractOptions.includeCount} is true. */
+  totalCount?: number;
 }
 
 /**
@@ -1610,6 +1615,9 @@ export interface GetOwnersForContractOptions {
 
   /** Optional page key to paginate the next page for large requests. */
   pageKey?: string;
+
+  /** If true, include total count of owners in the response. */
+  includeCount?: boolean;
 }
 
 /**

test/integration/nft.test.ts

@@ -227,6 +227,13 @@ describe('E2E integration tests', () => {
     expect(response.owners.length).toBeGreaterThan(0);
   });
 
+  it('getOwnersForContract() with includeCount', async () => {
+    const response = await alchemy.nft.getOwnersForContract(contractAddress, {
+      includeCount: true
+    });
+    expect(response.totalCount).not.toBeUndefined();
+  });
+
   it('getOwnersForContract()', async () => {
     const address = '0x57f1887a8BF19b14fC0dF6Fd9B2acc9Af147eA85';
     const response = await alchemy.nft.getOwnersForContract(address, {