opensea-js 7.3.2 → 7.4.0

package/README.md

@@ -29,6 +29,21 @@ Happy seafaring! ⛵️
 - [Frequently Asked Questions](developerDocs/faq.md)
 - [Contributing](developerDocs/contributing.md)
 
+### Security Warning
+
+**⚠️ Do not use this SDK directly in client-side/frontend applications.**
+
+The OpenSea SDK requires an API key for initialization. If you embed your API key in frontend code (e.g., browser applications, mobile apps), it will be publicly exposed and could be extracted by anyone, leading to potential abuse and rate limit issues.
+
+#### Recommended Architecture
+
+For frontend applications that need to interact with OpenSea functionality:
+
+1. **Create a backend API wrapper**: Set up your own backend server that securely stores your OpenSea API key
+2. **Call OpenSea SDK server-side**: Use opensea-js on your backend to interact with OpenSea's APIs
+3. **Return data to your frontend**: Send the necessary data (like transaction parameters) back to your frontend
+4. **Execute transactions in the browser**: Have users sign transactions with their own wallets (e.g., MetaMask) in the browser
+
 ## Changelog
 
 The changelog for recent versions can be found at:

package/lib/api/accounts.d.ts

@@ -0,0 +1,17 @@
+import { Chain, OpenSeaAccount, OpenSeaPaymentToken } from "../types";
+/**
+ * Account and payment token related API operations
+ */
+export declare class AccountsAPI {
+    private get;
+    private chain;
+    constructor(get: <T>(apiPath: string, query?: object) => Promise<T>, chain: Chain);
+    /**
+     * Fetch a payment token.
+     */
+    getPaymentToken(address: string, chain?: Chain): Promise<OpenSeaPaymentToken>;
+    /**
+     * Fetch account for an address.
+     */
+    getAccount(address: string): Promise<OpenSeaAccount>;
+}

package/lib/api/accounts.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccountsAPI = void 0;
+const apiPaths_1 = require("./apiPaths");
+const converters_1 = require("../utils/converters");
+/**
+ * Account and payment token related API operations
+ */
+class AccountsAPI {
+    constructor(get, chain) {
+        this.get = get;
+        this.chain = chain;
+    }
+    /**
+     * Fetch a payment token.
+     */
+    async getPaymentToken(address, chain = this.chain) {
+        const json = await this.get((0, apiPaths_1.getPaymentTokenPath)(chain, address));
+        return (0, converters_1.paymentTokenFromJSON)(json);
+    }
+    /**
+     * Fetch account for an address.
+     */
+    async getAccount(address) {
+        const json = await this.get((0, apiPaths_1.getAccountPath)(address));
+        return (0, converters_1.accountFromJSON)(json);
+    }
+}
+exports.AccountsAPI = AccountsAPI;
+//# sourceMappingURL=accounts.js.map

package/lib/api/accounts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accounts.js","sourceRoot":"","sources":["../../src/api/accounts.ts"],"names":[],"mappings":";;;AAAA,yCAAiE;AAEjE,oDAA4E;AAE5E;;GAEG;AACH,MAAa,WAAW;IACtB,YACU,GAAuD,EACvD,KAAY;QADZ,QAAG,GAAH,GAAG,CAAoD;QACvD,UAAK,GAAL,KAAK,CAAO;IACnB,CAAC;IAEJ;;OAEG;IACH,KAAK,CAAC,eAAe,CACnB,OAAe,EACf,KAAK,GAAG,IAAI,CAAC,KAAK;QAElB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,GAAG,CACzB,IAAA,8BAAmB,EAAC,KAAK,EAAE,OAAO,CAAC,CACpC,CAAC;QACF,OAAO,IAAA,iCAAoB,EAAC,IAAI,CAAC,CAAC;IACpC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,UAAU,CAAC,OAAe;QAC9B,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,GAAG,CAAiB,IAAA,yBAAc,EAAC,OAAO,CAAC,CAAC,CAAC;QACrE,OAAO,IAAA,4BAAe,EAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;CACF;AA1BD,kCA0BC"}

package/lib/api/api.d.ts

@@ -1,6 +1,6 @@
-import { BuildOfferResponse, GetCollectionsResponse, ListNFTsResponse, GetNFTResponse, ListCollectionOffersResponse, GetOrdersResponse, GetBestOfferResponse, GetBestListingResponse, GetOffersResponse, GetListingsResponse, CollectionOffer, CollectionOrderByOption, CancelOrderResponse } from "./types";
 import { FulfillmentDataResponse, OrderAPIOptions, OrdersQueryOptions, OrderV2, ProtocolData } from "../orders/types";
 import { Chain, OpenSeaAPIConfig, OpenSeaAccount, OpenSeaCollection, OpenSeaCollectionStats, OpenSeaPaymentToken, OrderSide } from "../types";
+import { BuildOfferResponse, GetCollectionsResponse, ListNFTsResponse, GetNFTResponse, ListCollectionOffersResponse, GetOrdersResponse, GetBestOfferResponse, GetBestListingResponse, GetOffersResponse, GetListingsResponse, CollectionOffer, CollectionOrderByOption, CancelOrderResponse, GetEventsArgs, GetEventsResponse } from "./types";
 /**
  * The API class for the OpenSea SDK.
  * @category Main Classes
@@ -20,6 +20,13 @@ export declare class OpenSeaAPI {
     logger: (arg: string) => void;
     private apiKey;
     private chain;
+    private ordersAPI;
+    private offersAPI;
+    private listingsAPI;
+    private collectionsAPI;
+    private nftsAPI;
+    private accountsAPI;
+    private eventsAPI;
     /**
      * Create an instance of the OpenSeaAPI
      * @param config OpenSeaAPIConfig for setting up the API, including an optional API key, Chain name, and base URL
@@ -28,40 +35,27 @@ export declare class OpenSeaAPI {
     constructor(config: OpenSeaAPIConfig, logger?: (arg: string) => void);
     /**
      * Gets an order from API based on query options.
-     * @param options
-     * @param options.side The side of the order (listing or offer)
-     * @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.maker Filter by the wallet address of the order maker
-     * @param options.taker 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
+     * @param options Query options for fetching an order
      * @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>;
+    getOrder(options: Omit<OrdersQueryOptions, "limit">): Promise<OrderV2>;
+    /**
+     * Gets a single order by its order hash.
+     * @param orderHash The hash of the order to fetch
+     * @param protocolAddress The address of the seaport contract
+     * @param chain The chain where the order is located. Defaults to the chain set in the constructor.
+     * @returns The {@link OrderV2} returned by the API
+     * @throws An error if the order is not found
+     */
+    getOrderByHash(orderHash: string, protocolAddress: string, chain?: Chain): Promise<OrderV2>;
     /**
      * 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.maker Filter by the wallet address of the order maker
-     * @param options.taker 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
+     * @param options Query options for fetching orders
      * @returns The {@link GetOrdersResponse} returned by the API.
      */
-    getOrders({ side, protocol, orderDirection, orderBy, ...restOptions }: Omit<OrdersQueryOptions, "limit">): Promise<GetOrdersResponse>;
+    getOrders(options: Omit<OrdersQueryOptions, "limit">): Promise<GetOrdersResponse>;
     /**
      * Gets all offers for a given collection.
      * @param collectionSlug The slug of the collection.
@@ -118,17 +112,15 @@ export declare class OpenSeaAPI {
      * @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)
+     * @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)
      * @returns The {@link FulfillmentDataResponse}
      */
-    generateFulfillmentData(fulfillerAddress: string, orderHash: string, protocolAddress: string, side: OrderSide): Promise<FulfillmentDataResponse>;
+    generateFulfillmentData(fulfillerAddress: string, orderHash: string, protocolAddress: string, side: OrderSide, assetContractAddress?: string, tokenId?: string): Promise<FulfillmentDataResponse>;
     /**
      * 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 apiOptions API options for the order
      * @returns The {@link OrderV2} posted to the API.
      */
     postOrder(order: ProtocolData, apiOptions: OrderAPIOptions): Promise<OrderV2>;
@@ -217,16 +209,15 @@ export declare class OpenSeaAPI {
     getCollectionStats(slug: string): Promise<OpenSeaCollectionStats>;
     /**
      * 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.
+     * @param address The address of the payment token
+     * @param chain The chain of the payment token
      * @returns The {@link OpenSeaPaymentToken} returned by the API.
      */
     getPaymentToken(address: string, chain?: Chain): Promise<OpenSeaPaymentToken>;
     /**
      * 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.
+     * @param address The address to fetch the account for
+     * @returns The {@link OpenSeaAccount} returned by the API.
      */
     getAccount(address: string): Promise<OpenSeaAccount>;
     /**
@@ -252,6 +243,35 @@ export declare class OpenSeaAPI {
      * @returns The response from the API.
      */
     offchainCancelOrder(protocolAddress: string, orderHash: string, chain?: Chain, offererSignature?: string): Promise<CancelOrderResponse>;
+    /**
+     * Gets a list of events based on query parameters.
+     * @param args Query parameters for filtering events.
+     * @returns The {@link GetEventsResponse} returned by the API.
+     */
+    getEvents(args?: GetEventsArgs): Promise<GetEventsResponse>;
+    /**
+     * Gets a list of events for a specific account.
+     * @param address The account address.
+     * @param args Query parameters for filtering events.
+     * @returns The {@link GetEventsResponse} returned by the API.
+     */
+    getEventsByAccount(address: string, args?: GetEventsArgs): Promise<GetEventsResponse>;
+    /**
+     * Gets a list of events for a specific collection.
+     * @param collectionSlug The slug (identifier) of the collection.
+     * @param args Query parameters for filtering events.
+     * @returns The {@link GetEventsResponse} returned by the API.
+     */
+    getEventsByCollection(collectionSlug: string, args?: GetEventsArgs): Promise<GetEventsResponse>;
+    /**
+     * Gets a list of events for a specific NFT.
+     * @param chain The chain where the NFT is located.
+     * @param address The contract address of the NFT.
+     * @param identifier The token identifier.
+     * @param args Query parameters for filtering events.
+     * @returns The {@link GetEventsResponse} returned by the API.
+     */
+    getEventsByNFT(chain: Chain, address: string, identifier: string, args?: GetEventsArgs): Promise<GetEventsResponse>;
     /**
      * Generic fetch method for any API endpoint
      * @param apiPath Path to URL endpoint under API