opensea-js 6.1.5 → 6.1.6

package/lib/api/api.d.ts

@@ -1,14 +1,18 @@
 import { ethers } from "ethers";
-import { BuildOfferResponse, Offer, ListNFTsResponse, GetNFTResponse, ListCollectionOffersResponse } from "./types";
-import { FulfillmentDataResponse, OrderAPIOptions, OrderSide, OrdersQueryOptions, OrderV2, ProtocolData, QueryCursors } from "../orders/types";
-import { Chain, OpenSeaAPIConfig, OpenSeaAsset, OpenSeaAssetBundle, OpenSeaAssetBundleQuery, OpenSeaAssetQuery, OpenSeaCollection, OpenSeaFungibleToken, OpenSeaFungibleTokenQuery } from "../types";
+import { BuildOfferResponse, Offer, ListNFTsResponse, GetNFTResponse, ListCollectionOffersResponse, GetAssetsResponse, GetOrdersResponse, GetPaymentTokensResponse, GetBundlesResponse } from "./types";
+import { FulfillmentDataResponse, OrderAPIOptions, OrderSide, OrdersQueryOptions, OrderV2, ProtocolData } from "../orders/types";
+import { Chain, OpenSeaAPIConfig, OpenSeaAsset, OpenSeaAssetBundle, OpenSeaAssetBundleQuery, OpenSeaAssetQuery, OpenSeaCollection, OpenSeaFungibleTokenQuery } from "../types";
+/**
+ * The API class for the OpenSea SDK.
+ * @category Main Classes
+ */
 export declare class OpenSeaAPI {
     /**
      * Base url for the API
      */
     readonly apiBaseUrl: string;
     /**
-     * Page size to use for fetching orders
+     * Default size to use for fetching orders
      */
     pageSize: number;
     /**
@@ -25,150 +29,197 @@ export declare class OpenSeaAPI {
      */
     constructor(config: OpenSeaAPIConfig, logger?: (arg: string) => void);
     /**
-     * Gets an order from API based on query options. Throws when no order is found.
+     * Gets an order from API based on query options.
+     * @param options
+     * @param options.side The side of the order (buy or sell
+     * @param options.protocol The protocol, typically seaport, to query orders for
+     * @param options.orderDirection The direction to sort the orders
+     * @param options.orderBy The field to sort the orders by
+     * @param options.limit The number of orders to retrieve
+     * @param options.makerAddress Fitler by the wallet addres of the order maker
+     * @param options.takerAddress Filter by  wallet address of the order taker
+     * @param options.asset_contract_address Address of the NFT's contract
+     * @param options.token_ids String array of token IDs to filter by.
+     * @param options.listed_after Filter by orders listed after the Unix epoch timestamp in seconds
+     * @param options.listed_before Filter by orders listed before the Unix epoch timestamp in seconds
+     * @returns The first {@link OrderV2} returned by the API
+     *
+     * @throws An error if there are no matching orders.
      */
     getOrder({ side, protocol, orderDirection, orderBy, ...restOptions }: Omit<OrdersQueryOptions, "limit">): Promise<OrderV2>;
     /**
-     * Gets a list of orders from API based on query options and returns orders
-     * with next and previous cursors.
-     */
-    getOrders({ side, protocol, orderDirection, orderBy, ...restOptions }: Omit<OrdersQueryOptions, "limit">): Promise<QueryCursors & {
-        orders: OrderV2[];
-    }>;
-    /**
-     * Generate the data needed to fulfill a listing or an offer
+     * Gets a list of orders from API based on query options.
+     * @param options
+     * @param options.side The side of the order (buy or sell)
+     * @param options.protocol The protocol, typically seaport, to query orders for
+     * @param options.orderDirection The direction to sort the orders
+     * @param options.orderBy The field to sort the orders by
+     * @param options.limit The number of orders to retrieve
+     * @param options.makerAddress Fitler by the wallet addres of the order maker
+     * @param options.takerAddress Filter by  wallet address of the order taker
+     * @param options.asset_contract_address Address of the NFT's contract
+     * @param options.token_ids String array of token IDs to filter by.
+     * @param options.listed_after Filter by orders listed after the Unix epoch timestamp in seconds
+     * @param options.listed_before Filter by orders listed before the Unix epoch timestamp in seconds
+     * @returns The {@link GetOrdersResponse} returned by the API.
+     */
+    getOrders({ side, protocol, orderDirection, orderBy, ...restOptions }: Omit<OrdersQueryOptions, "limit">): Promise<GetOrdersResponse>;
+    /**
+     * 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
+     * @param orderHash The hash of the order to fulfill
+     * @param protocolAddress The address of the seaport contract
+     * @side The side of the order (buy or sell)
+     * @returns The {@link FulfillmentDataResponse}
      */
     generateFulfillmentData(fulfillerAddress: string, orderHash: string, protocolAddress: string, side: OrderSide): Promise<FulfillmentDataResponse>;
     /**
-     * Send an order to be posted. Throws when the order is invalid.
+     * Post an order to OpenSea.
+     * @param order The order to post
+     * @param apiOptions
+     * @param apiOptions.protocol The protocol, typically seaport, to post the order to.
+     * @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>;
     /**
-     * Build an offer
+     * 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.
+     * @returns The {@link BuildOfferResponse} returned by the API.
      */
     buildOffer(offererAddress: string, quantity: number, collectionSlug: string): Promise<BuildOfferResponse>;
     /**
-     * Get collection offers for a given slug in the API
-     *
-     * @param slug The collection you would like to list offers for
-     * @param retries Number of times to retry if the service is unavailable for any reason
-     *
-     * @returns {@link ListCollectionOffersResponse}
+     * 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>;
     /**
-     * Post a collection offer to the API
-     *
-     * @param order The order to post
-     * @param slug The collection you would like to post an offer for
-     * @param retries Number of times to retry if the service is unavailable for any reason
-     *
-     * @returns {@link Offer}
+     * 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<Offer | null>;
     /**
-     * Fetch an asset from the API, throwing if none is found
-     *
-     * @deprecated Please use `getNFT()` for multichain capabilities.
-     *
-     * @param tokenAddress Address of the asset's contract
-     * @param tokenId The asset's token ID, or null if ERC-20
+     * 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>;
     /**
-     * Fetch multiple NFTs for a collection from the API
-     * @param slug The collection you would like to list NFTs for
+     * 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
+     * @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>;
     /**
-     * Fetch multiple NFTs for a contract from the API
-     * @param chain chain the contract is deployed to
-     * @param address address of the smart contract
+     * 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 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.
      */
     getNFTsByContract(chain: Chain, address: string, limit?: number | undefined, next?: string | undefined, retries?: number): Promise<ListNFTsResponse>;
     /**
-     * Fetch metadata, traits, ownership information, and rarity for an NFT from the API
-     * @param chain chain the contract is deployed to
-     * @param address address of the smart contract
-     * @param identifierthe identifier of the NFT (i.e. token_id)
+     * 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
+     * @returns The {@link GetNFTResponse} returned by the API.
      */
     getNFT(chain: Chain, address: string, identifier: string, retries?: number): Promise<GetNFTResponse>;
     /**
-     * Fetch list of assets from the API, returning the page of assets and the count of total assets
-     *
-     * @deprecated Please use `getNFTsByContract()` or `getNFTsByCollection()` for multichain capabilities.
-     *
-     * @param query Query to use for getting orders. A subset of parameters on the `OpenSeaAssetJSON` type is supported
-     */
-    getAssets(query?: OpenSeaAssetQuery): Promise<{
-        assets: OpenSeaAsset[];
-        estimatedCount: number;
-        next: string | undefined;
-        previous: string | undefined;
-    }>;
-    /**
-     * Fetch a collection through the API
+     * 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>;
+    /**
+     * Fetch an OpenSea collection.
+     * @param slug The slug (identifier) of the collection.
+     * @returns The {@link OpenSeaCollection} returned by the API.
      */
     getCollection(slug: string): Promise<OpenSeaCollection>;
     /**
-     * Fetch list of fungible tokens from the API matching parameters
-     * @param query Query to use for getting orders. A subset of parameters on the `OpenSeaAssetJSON` type is supported
-     * @param page Page number, defaults to 1. Can be overridden by
-     * `limit` and `offset` attributes from OpenSeaFungibleTokenQuery
-     * @param retries Number of times to retry if the service is unavailable for any reason
+     * 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.
      */
-    getPaymentTokens(query?: OpenSeaFungibleTokenQuery, page?: number, retries?: number): Promise<{
-        tokens: OpenSeaFungibleToken[];
-    }>;
+    getPaymentTokens(query?: OpenSeaFungibleTokenQuery, page?: number, retries?: number): Promise<GetPaymentTokensResponse>;
     /**
-     * Fetch a bundle from the API, return null if it isn't found
-     * @param slug The bundle's identifier
+     * 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.
      */
     getBundle({ slug, }: {
         slug: string;
     }): Promise<OpenSeaAssetBundle | null>;
     /**
-     * Fetch list of bundles from the API, returning the page of bundles and the count of total bundles
-     * @param query Query to use for getting orders. A subset of parameters on the `OpenSeaAssetBundleJSON` type is supported
-     * @param page Page number, defaults to 1. Can be overridden by
-     * `limit` and `offset` attributes from OpenSeaAssetBundleQuery
+     * Fetch list of bundles from the API.
+     * @param query Query to use for getting bunldes. See {@link OpenSeaAssetBundleQuery}.
+     * @param page Page number to fetch. Defaults to 1.
+     * @returns The {@link GetBundlesResponse} returned by the API.
      */
-    getBundles(query?: OpenSeaAssetBundleQuery, page?: number): Promise<{
-        bundles: OpenSeaAssetBundle[];
-        estimatedCount: number;
-    }>;
+    getBundles(query?: OpenSeaAssetBundleQuery, page?: number): Promise<GetBundlesResponse>;
     /**
-     * Used to force refresh the metadata for an NFT from the API
-     * @param chain chain the contract is deployed to
-     * @param address address of the smart contract
-     * @param identifierthe identifier of the NFT (i.e. token_id)
-     * @param retries Number of times to retry if the service is unavailable for any reason
+     * 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.
+     * @returns The response from the API.
      */
-    refreshNFTMetadata(chain: Chain, address: string, identifier: string, retries?: number): Promise<unknown>;
+    refreshNFTMetadata(chain: Chain, address: string, identifier: string, retries?: number): Promise<Response>;
     /**
-     * Get JSON data from API, sending auth token in headers
+     * Generic fetch method for any API endpoint
      * @param apiPath Path to URL endpoint under API
-     * @param query Data to send. Will be stringified using QueryString
+     * @param query URL query params. Will be used to create a URLSearchParams object.
+     * @returns @typeParam T The response from the API.
      */
     get<T>(apiPath: string, query?: object): Promise<T>;
     /**
-     * POST JSON data to API, sending auth token in headers
+     * Generic post methd for any API endpoint.
      * @param apiPath Path to URL endpoint under API
-     * @param body Data to send. Will be JSON.stringified
+     * @param body Data to send.
      * @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>;
     private objectToSearchParams;