feat: default unitsToFill to 1 for offers and listings, add includePrivateListings parameter

package.json

@@ -1,6 +1,6 @@
 {
   "name": "opensea-js",
-  "version": "8.0.4",
+  "version": "8.0.5",
   "description": "TypeScript SDK for the OpenSea marketplace helps developers build new experiences using NFTs and our marketplace data",
   "license": "MIT",
   "author": "OpenSea Developers",

src/api/api.ts

@@ -169,14 +169,21 @@ export class OpenSeaAPI {
    * @param collectionSlug The slug of the collection.
    * @param limit The number of listings to return. Must be between 1 and 100. Default: 100
    * @param next The cursor for the next page of results. This is returned from a previous request.
+   * @param includePrivateListings Whether to include private listings (default: false)
    * @returns The {@link GetListingsResponse} returned by the API.
    */
   public async getAllListings(
     collectionSlug: string,
     limit?: number,
     next?: string,
+    includePrivateListings?: boolean,
   ): Promise<GetListingsResponse> {
-    return this.listingsAPI.getAllListings(collectionSlug, limit, next);
+    return this.listingsAPI.getAllListings(
+      collectionSlug,
+      limit,
+      next,
+      includePrivateListings,
+    );
   }
 
   /**
@@ -227,28 +234,41 @@ export class OpenSeaAPI {
    * Gets the best listing for a given token.
    * @param collectionSlug The slug of the collection.
    * @param tokenId The token identifier.
+   * @param includePrivateListings Whether to include private listings (default: false)
    * @returns The {@link GetBestListingResponse} returned by the API.
    */
   public async getBestListing(
     collectionSlug: string,
     tokenId: string | number,
+    includePrivateListings?: boolean,
   ): Promise<GetBestListingResponse> {
-    return this.listingsAPI.getBestListing(collectionSlug, tokenId);
+    return this.listingsAPI.getBestListing(
+      collectionSlug,
+      tokenId,
+      includePrivateListings,
+    );
   }
 
   /**
    * Gets the best listings for a given collection.
    * @param collectionSlug The slug of the collection.
    * @param limit The number of listings to return. Must be between 1 and 100. Default: 100
    * @param next The cursor for the next page of results. This is returned from a previous request.
+   * @param includePrivateListings Whether to include private listings (default: false)
    * @returns The {@link GetListingsResponse} returned by the API.
    */
   public async getBestListings(
     collectionSlug: string,
     limit?: number,
     next?: string,
+    includePrivateListings?: boolean,
   ): Promise<GetListingsResponse> {
-    return this.listingsAPI.getBestListings(collectionSlug, limit, next);
+    return this.listingsAPI.getBestListings(
+      collectionSlug,
+      limit,
+      next,
+      includePrivateListings,
+    );
   }
 
   /**
@@ -259,7 +279,7 @@ export class OpenSeaAPI {
    * @side The side of the order (buy or sell)
    * @param assetContractAddress Optional address of the NFT contract for criteria offers (e.g., collection offers)
    * @param tokenId Optional token ID for criteria offers (e.g., collection offers)
-   * @param unitsToFill Optional number of units to fill. For listings, defaults to remaining quantity. For offers, defaults to 1.
+   * @param unitsToFill Optional number of units to fill. Defaults to 1 for both listings and offers.
    * @param recipientAddress Optional recipient address for the NFT when fulfilling a listing. Not applicable for offers.
    * @returns The {@link FulfillmentDataResponse}
    */
@@ -642,6 +662,7 @@ export class OpenSeaAPI {
    * @param limit The number of listings to return. Must be between 1 and 100.
    * @param next The cursor for the next page of results. This is returned from a previous request.
    * @param chain The chain where the NFT is located. Defaults to the chain set in the constructor.
+   * @param includePrivateListings Whether to include private listings (default: false)
    * @returns The {@link GetListingsResponse} returned by the API.
    */
   public async getNFTListings(
@@ -650,13 +671,15 @@ export class OpenSeaAPI {
     limit?: number,
     next?: string,
     chain: Chain = this.chain,
+    includePrivateListings?: boolean,
   ): Promise<GetListingsResponse> {
     return this.listingsAPI.getNFTListings(
       assetContractAddress,
       tokenId,
       limit,
       next,
       chain,
+      includePrivateListings,
     );
   }
 

src/api/listings.ts

@@ -20,71 +20,106 @@ export class ListingsAPI {
 
   /**
    * Gets all listings for a given collection.
+   * @param collectionSlug The collection slug
+   * @param limit The number of listings to return
+   * @param next The cursor for pagination
+   * @param includePrivateListings Whether to include private listings (default: false)
    */
   async getAllListings(
     collectionSlug: string,
     limit?: number,
     next?: string,
+    includePrivateListings?: boolean,
   ): Promise<GetListingsResponse> {
     const response = await this.fetcher.get<GetListingsResponse>(
       getAllListingsAPIPath(collectionSlug),
       {
         limit,
         next,
+        ...(includePrivateListings !== undefined && {
+          include_private_listings: includePrivateListings,
+        }),
       },
     );
     return response;
   }
 
   /**
    * Gets the best listing for a given token.
+   * @param collectionSlug The collection slug
+   * @param tokenId The token ID
+   * @param includePrivateListings Whether to include private listings (default: false)
    */
   async getBestListing(
     collectionSlug: string,
     tokenId: string | number,
+    includePrivateListings?: boolean,
   ): Promise<GetBestListingResponse> {
     const response = await this.fetcher.get<GetBestListingResponse>(
       getBestListingAPIPath(collectionSlug, tokenId),
+      includePrivateListings !== undefined
+        ? { include_private_listings: includePrivateListings }
+        : undefined,
     );
     return response;
   }
 
   /**
    * Gets the best listings for a given collection.
+   * @param collectionSlug The collection slug
+   * @param limit The number of listings to return
+   * @param next The cursor for pagination
+   * @param includePrivateListings Whether to include private listings (default: false)
    */
   async getBestListings(
     collectionSlug: string,
     limit?: number,
     next?: string,
+    includePrivateListings?: boolean,
   ): Promise<GetListingsResponse> {
     const response = await this.fetcher.get<GetListingsResponse>(
       getBestListingsAPIPath(collectionSlug),
       {
         limit,
         next,
+        ...(includePrivateListings !== undefined && {
+          include_private_listings: includePrivateListings,
+        }),
       },
     );
     return response;
   }
 
   /**
    * Gets all active listings for a specific NFT.
+   * @param assetContractAddress The NFT contract address
+   * @param tokenId The token ID
+   * @param limit The number of listings to return
+   * @param next The cursor for pagination
+   * @param chain The blockchain chain
+   * @param includePrivateListings Whether to include private listings (default: false)
    */
   async getNFTListings(
     assetContractAddress: string,
     tokenId: string,
     limit?: number,
     next?: string,
     chain: Chain = this.chain,
+    includePrivateListings?: boolean,
   ): Promise<GetListingsResponse> {
     const response = await this.fetcher.get<GetListingsResponse>(
       getOrdersAPIPath(chain, "seaport", OrderSide.LISTING),
-      serializeOrdersQueryOptions({
-        assetContractAddress,
-        tokenIds: [tokenId],
-        limit,
-        next,
-      }),
+      {
+        ...serializeOrdersQueryOptions({
+          assetContractAddress,
+          tokenIds: [tokenId],
+          limit,
+          next,
+        }),
+        ...(includePrivateListings !== undefined && {
+          include_private_listings: includePrivateListings,
+        }),
+      },
     );
     return response;
   }