opensea-js 6.1.15 → 7.0.0

package/README.md

@@ -12,11 +12,11 @@
 
 # OpenSea.js <!-- omit in toc -->
 
-This is the JavaScript SDK for [OpenSea](https://opensea.io), the largest marketplace for NFTs.
+This is the TypeScript SDK for [OpenSea](https://opensea.io), the largest marketplace for NFTs.
 
 It allows developers to access the official orderbook, filter it, create listings and offers, and complete trades programmatically.
 
-Get started by [requesting an API key](https://docs.opensea.io/reference/api-keys) and instantiating your own OpenSea SDK instance. Then you can create orders off-chain or fulfill orders on-chain, and listen to events (like `ApproveAllAssets` or `WrapEth`) in the process.
+Get started by [requesting an API key](https://docs.opensea.io/reference/api-keys) and instantiating your own OpenSea SDK instance. Then you can create orders off-chain or fulfill orders on-chain, and listen to events in the process.
 
 Happy seafaring! ⛵️
 

package/lib/api/api.d.ts

@@ -1,7 +1,6 @@
-import { ethers } from "ethers";
-import { BuildOfferResponse, ListNFTsResponse, GetNFTResponse, ListCollectionOffersResponse, GetAssetsResponse, GetOrdersResponse, GetPaymentTokensResponse, GetBundlesResponse, GetBestOfferResponse, GetBestListingResponse, GetOffersResponse, GetListingsResponse, CollectionOffer } from "./types";
-import { FulfillmentDataResponse, OrderAPIOptions, OrderSide, OrdersQueryOptions, OrderV2, ProtocolData } from "../orders/types";
-import { Chain, OpenSeaAPIConfig, OpenSeaAsset, OpenSeaAssetBundle, OpenSeaAssetBundleQuery, OpenSeaAssetQuery, OpenSeaCollection, OpenSeaFungibleTokenQuery } from "../types";
+import { BuildOfferResponse, ListNFTsResponse, GetNFTResponse, ListCollectionOffersResponse, GetOrdersResponse, GetBestOfferResponse, GetBestListingResponse, GetOffersResponse, GetListingsResponse, CollectionOffer } from "./types";
+import { FulfillmentDataResponse, OrderAPIOptions, OrdersQueryOptions, OrderV2, ProtocolData } from "../orders/types";
+import { Chain, OpenSeaAPIConfig, OpenSeaAccount, OpenSeaCollection, OpenSeaCollectionStats, OpenSeaPaymentToken, OrderSide } from "../types";
 /**
  * The API class for the OpenSea SDK.
  * @category Main Classes
@@ -21,11 +20,10 @@ export declare class OpenSeaAPI {
     logger: (arg: string) => void;
     private apiKey;
     private chain;
-    private retryDelay;
     /**
-     * Create an instance of the OpenSea API
+     * Create an instance of the OpenSeaAPI
      * @param config OpenSeaAPIConfig for setting up the API, including an optional API key, Chain name, and base URL
-     * @param logger Optional function for logging debug strings before and after requests are made
+     * @param logger Optional function for logging debug strings before and after requests are made. Defaults to no logging
      */
     constructor(config: OpenSeaAPIConfig, logger?: (arg: string) => void);
     /**
@@ -94,6 +92,12 @@ export declare class OpenSeaAPI {
      * @returns The {@link GetBestListingResponse} returned by the API.
      */
     getBestListing(collectionSlug: string, tokenId: string | number): Promise<GetBestListingResponse>;
+    /**
+     * Gets the best listing for a given collection.
+     * @param collectionSlug The slug of the collection.
+     * @returns The {@link GetListingsResponse} returned by the API.
+     */
+    getBestListings(collectionSlug: string): Promise<GetListingsResponse>;
     /**
      * Generate the data needed to fulfill a listing or an offer onchain.
      * @param fulfillerAddress The wallet address which will be used to fulfill the order
@@ -111,102 +115,65 @@ export declare class OpenSeaAPI {
      * @param apiOptions.side The side of the order (buy or sell).
      * @param apiOptions.protocolAddress The address of the seaport contract.
      * @param options
-     * @param options.retries Number of times to retry if the service is unavailable for any reason.
      * @returns The {@link OrderV2} posted to the API.
      */
-    postOrder(order: ProtocolData, apiOptions: OrderAPIOptions, { retries }?: {
-        retries?: number;
-    }): Promise<OrderV2>;
+    postOrder(order: ProtocolData, apiOptions: OrderAPIOptions): Promise<OrderV2>;
     /**
      * Build a OpenSea collection offer.
      * @param offererAddress The wallet address which is creating the offer.
      * @param quantity The number of NFTs requested in the offer.
      * @param collectionSlug The slug (identifier) of the collection to build the offer for.
+     * @param offerProtectionEnabled Build the offer on OpenSea's signed zone to provide offer protections from receiving an item which is disabled from trading.
      * @returns The {@link BuildOfferResponse} returned by the API.
      */
-    buildOffer(offererAddress: string, quantity: number, collectionSlug: string): Promise<BuildOfferResponse>;
+    buildOffer(offererAddress: string, quantity: number, collectionSlug: string, offerProtectionEnabled?: boolean): Promise<BuildOfferResponse>;
     /**
      * Get a list collection offers for a given slug.
      * @param slug The slug (identifier) of the collection to list offers for
-     * @param retries Number of times to retry if the service is unavailable for any reason.
      * @returns The {@link ListCollectionOffersResponse} returned by the API.
      */
-    getCollectionOffers(slug: string, retries?: number): Promise<ListCollectionOffersResponse | null>;
+    getCollectionOffers(slug: string): Promise<ListCollectionOffersResponse | null>;
     /**
      * Post a collection offer to OpenSea.
      * @param order The collection offer to post.
      * @param slug The slug (identifier) of the collection to post the offer for.
-     * @param retries Number of times to retry if the service is unavailable for any reason.
      * @returns The {@link Offer} returned to the API.
      */
-    postCollectionOffer(order: ProtocolData, slug: string, retries?: number): Promise<CollectionOffer | null>;
-    /**
-     * Fetch an asset.
-     * @deprecated Use {@link getNFT} for multichain capabilities.
-     * @param options
-     * @param options.tokenAddress The asset's contract address.
-     * @param options.tokenId The asset's token ID, or null if ERC-20
-     * @param retries Number of times to retry if the service is unavailable for any reason
-     * @returns The {@link OpenSeaAsset} returned by the API.
-     * @throws An error if the function is called on an unsupported chain.
-     */
-    getAsset({ tokenAddress, tokenId, }: {
-        tokenAddress: string;
-        tokenId: string | number | null;
-    }, retries?: number): Promise<OpenSeaAsset>;
+    postCollectionOffer(order: ProtocolData, slug: string): Promise<CollectionOffer | null>;
     /**
      * Fetch multiple NFTs for a collection.
      * @param slug The slug (identifier) of the collection
      * @param limit The number of NFTs to retrieve. Must be greater than 0 and less than 51.
      * @param next Cursor to retrieve the next page of NFTs
-     * @param retries Number of times to retry if the service is unavailable for any reason.
      * @returns The {@link ListNFTsResponse} returned by the API.
      */
-    getNFTsByCollection(slug: string, limit?: number | undefined, next?: string | undefined, retries?: number): Promise<ListNFTsResponse>;
+    getNFTsByCollection(slug: string, limit?: number | undefined, next?: string | undefined): Promise<ListNFTsResponse>;
     /**
      * Fetch multiple NFTs for a contract.
-     * @param chain The NFT's chain.
      * @param address The NFT's contract address.
      * @param limit The number of NFTs to retrieve. Must be greater than 0 and less than 51.
      * @param next Cursor to retrieve the next page of NFTs.
-     * @param retries Number of times to retry if the service is unavailable for any reason.
+     * @param chain The NFT's chain.
      * @returns The {@link ListNFTsResponse} returned by the API.
      */
-    getNFTsByContract(chain: Chain, address: string, limit?: number | undefined, next?: string | undefined, retries?: number): Promise<ListNFTsResponse>;
+    getNFTsByContract(address: string, limit?: number | undefined, next?: string | undefined, chain?: Chain): Promise<ListNFTsResponse>;
     /**
      * Fetch NFTs owned by an account.
      * @param address The address of the account
      * @param limit The number of NFTs to retrieve. Must be greater than 0 and less than 51.
      * @param next Cursor to retrieve the next page of NFTs
-     * @param retries Number of times to retry if the service is unavailable for any reason.
      * @param chain The chain to query. Defaults to the chain set in the constructor.
      * @returns The {@link ListNFTsResponse} returned by the API.
      */
-    getNFTsByAccount(address: string, limit?: number | undefined, next?: string | undefined, retries?: number, chain?: Chain): Promise<ListNFTsResponse>;
+    getNFTsByAccount(address: string, limit?: number | undefined, next?: string | undefined, chain?: Chain): Promise<ListNFTsResponse>;
     /**
      * Fetch metadata, traits, ownership information, and rarity for a single NFT.
-     * @param chain The NFT's chain.
      * @param address The NFT's contract address.
      * @param identifier the identifier of the NFT (i.e. Token ID)
-     * @param retries Number of times to retry if the service is unavailable for any reason
+     * @param chain The NFT's chain.
      * @returns The {@link GetNFTResponse} returned by the API.
      */
-    getNFT(chain: Chain, address: string, identifier: string, retries?: number): Promise<GetNFTResponse>;
-    /**
-     * Fetch a list of assets.
-     * @deprecated Use {@link getNFTsByContract} or {@link getNFTsByCollection} for multichain capabilities.
-     * @param query Options to filter the list returned.
-     * @param query.owner The wallet address of the owner of the assets.
-     * @param query.asset_contract_address The Asset's contract address.
-     * @param query.token_ids String array of token IDs to filter by.
-     * @param query.order_by The field to order the list by.
-     * @param query.order_direction The direction to order the list.
-     * @param query.limit The number of assets to retrieve. Must be greater than 0 and less than 201.
-     * @param query.cursor Cursor to retrieve the next page of assets.
-     * @throws An error if the function is called on an unsupported chain.
-     * @returns The {@link GetAssetsResponse} returned by the API.
-     */
-    getAssets(query?: OpenSeaAssetQuery): Promise<GetAssetsResponse>;
+    getNFT(address: string, identifier: string, chain?: Chain): Promise<GetNFTResponse>;
     /**
      * Fetch an OpenSea collection.
      * @param slug The slug (identifier) of the collection.
@@ -214,39 +181,33 @@ export declare class OpenSeaAPI {
      */
     getCollection(slug: string): Promise<OpenSeaCollection>;
     /**
-     * Fetch list of fungible tokens.
-     * @param query Query to use for getting tokens. See {@link OpenSeaFungibleTokenQuery}.
-     * @param page Page number to fetch. Defaults to 1.
-     * @param retries Number of times to retry if the service is unavailable for any reason.
-     * @throws An error if the function is called on an unsupported chain.
-     * @returns The {@link GetPaymentTokensResponse} returned by the API.
+     * Fetch stats for an OpenSea collection.
+     * @param slug The slug (identifier) of the collection.
+     * @returns The {@link OpenSeaCollection} returned by the API.
      */
-    getPaymentTokens(query?: OpenSeaFungibleTokenQuery, page?: number, retries?: number): Promise<GetPaymentTokensResponse>;
+    getCollectionStats(slug: string): Promise<OpenSeaCollectionStats>;
     /**
-     * Fetch a bundle from the API.
-     * @param options
-     * @param options.slug The bundle's identifier
-     * @returns The {@link OpenSeaAssetBundle} returned by the API. If not found, returns null.
+     * Fetch a payment token.
+     * @param query Query to use for getting tokens. See {@link OpenSeaPaymentTokenQuery}.
+     * @param next The cursor for the next page of results. This is returned from a previous request.
+     * @returns The {@link OpenSeaPaymentToken} returned by the API.
      */
-    getBundle({ slug, }: {
-        slug: string;
-    }): Promise<OpenSeaAssetBundle | null>;
+    getPaymentToken(address: string, chain?: Chain): Promise<OpenSeaPaymentToken>;
     /**
-     * Fetch list of bundles from the API.
-     * @param query Query to use for getting bundles. See {@link OpenSeaAssetBundleQuery}.
-     * @param page Page number to fetch. Defaults to 1.
-     * @returns The {@link GetBundlesResponse} returned by the API.
+     * Fetch account for an address.
+     * @param query Query to use for getting tokens. See {@link OpenSeaPaymentTokenQuery}.
+     * @param next The cursor for the next page of results. This is returned from a previous request.
+     * @returns The {@link GetAccountResponse} returned by the API.
      */
-    getBundles(query?: OpenSeaAssetBundleQuery, page?: number): Promise<GetBundlesResponse>;
+    getAccount(address: string): Promise<OpenSeaAccount>;
     /**
      * Force refresh the metadata for an NFT.
-     * @param chain The chain where the NFT is located.
      * @param address The address of the NFT's contract.
      * @param identifier The identifier of the NFT.
-     * @param retries Number of times to retry if the service is unavailable for any reason.
+     * @param chain The chain where the NFT is located.
      * @returns The response from the API.
      */
-    refreshNFTMetadata(chain: Chain, address: string, identifier: string, retries?: number): Promise<Response>;
+    refreshNFTMetadata(address: string, identifier: string, chain?: Chain): Promise<Response>;
     /**
      * Generic fetch method for any API endpoint
      * @param apiPath Path to URL endpoint under API
@@ -261,7 +222,7 @@ export declare class OpenSeaAPI {
      * @param opts ethers ConnectionInfo, similar to Fetch API.
      * @returns @typeParam T The response from the API.
      */
-    post<T>(apiPath: string, body?: object, opts?: ethers.utils.ConnectionInfo): Promise<T>;
+    post<T>(apiPath: string, body?: object, opts?: object): Promise<T>;
     private objectToSearchParams;
     /**
      * Get from an API Endpoint, sending auth token in headers