feat: add postListing/postOffer API methods, deprecate legacy order endpoints (#1936)

* feat: migrate from deprecated order response to v2 listing/offer types

The os2-core POST listing/offer endpoints now return both a deprecated
`order` field and new `listing`/`offer` fields with the v2 response
format. This PR migrates the SDK to read from the new fields.

BREAKING CHANGES:
- `createListing` now returns `Listing` instead of `OrderV2`
- `createOffer` now returns `Offer` instead of `OrderV2`
- `createBulkListings` returns `BulkListingResult` instead of `BulkOrderResult`
- `createBulkOffers` returns `BulkOfferResult` instead of `BulkOrderResult`
- New `postListing`/`postOffer` API methods replace deprecated `postOrder`
- GET orders endpoints (`getOrder`/`getOrders`) marked as deprecated

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* refactor: add new postListing/postOffer API methods (non-breaking)

Add new API methods that return native Listing/Offer types from the
upcoming os2-core response format changes. Existing methods and return
types are preserved — consumers can migrate at their own pace.

- Add postListing() and postOffer() on OpenSeaAPI and OrdersAPI
- Add ListingPostQueryResponse and OfferPostQueryResponse types
- Mark deprecated methods with @deprecated JSDoc annotations

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: ryanio

src/api/api.ts

@@ -51,6 +51,8 @@ import {
   GetSwapQuoteArgs,
   GetSwapQuoteResponse,
   GetTokenResponse,
+  Listing,
+  Offer,
   SearchArgs,
   SearchResponse,
 } from "./types";
@@ -126,6 +128,7 @@ export class OpenSeaAPI {
 
   /**
    * Gets an order from API based on query options.
+   * @deprecated Use collection-based endpoints instead: getAllOffers, getAllListings, getBestOffer, getBestListing.
    * @param options Query options for fetching an order
    * @returns The first {@link OrderV2} returned by the API
    *
@@ -155,6 +158,7 @@ export class OpenSeaAPI {
 
   /**
    * Gets a list of orders from API based on query options.
+   * @deprecated Use collection-based endpoints instead: getAllOffers, getAllListings, getBestOffer, getBestListing.
    * @param options Query options for fetching orders
    * @returns The {@link GetOrdersResponse} returned by the API.
    */
@@ -325,6 +329,7 @@ export class OpenSeaAPI {
 
   /**
    * Post an order to OpenSea.
+   * @deprecated Use postListing or postOffer instead.
    * @param order The order to post
    * @param apiOptions API options for the order
    * @returns The {@link OrderV2} posted to the API.
@@ -336,6 +341,32 @@ export class OpenSeaAPI {
     return this.ordersAPI.postOrder(order, apiOptions);
   }
 
+  /**
+   * Post a listing to OpenSea. Returns the new v2 Listing response format.
+   * @param order The order to post
+   * @param protocolAddress The contract address of the seaport protocol
+   * @returns The {@link Listing} posted to the API.
+   */
+  public async postListing(
+    order: ProtocolData,
+    protocolAddress: string,
+  ): Promise<Listing> {
+    return this.ordersAPI.postListing(order, protocolAddress);
+  }
+
+  /**
+   * Post an offer to OpenSea. Returns the new v2 Offer response format.
+   * @param order The order to post
+   * @param protocolAddress The contract address of the seaport protocol
+   * @returns The {@link Offer} posted to the API.
+   */
+  public async postOffer(
+    order: ProtocolData,
+    protocolAddress: string,
+  ): Promise<Offer> {
+    return this.ordersAPI.postOffer(order, protocolAddress);
+  }
+
   /**
    * Build a OpenSea collection offer.
    * @param offererAddress The wallet address which is creating the offer.

src/api/orders.ts

@@ -7,9 +7,13 @@ import {
   GetOrdersResponse,
   CancelOrderResponse,
   GetOrderByHashResponse,
+  Listing,
+  Offer,
 } from "./types";
 import {
   FulfillmentDataResponse,
+  ListingPostQueryResponse,
+  OfferPostQueryResponse,
   OrderAPIOptions,
   OrdersPostQueryResponse,
   OrdersQueryOptions,
@@ -38,6 +42,7 @@ export class OrdersAPI {
 
   /**
    * Gets an order from API based on query options.
+   * @deprecated Use collection-based endpoints instead: getAllOffers, getAllListings, getBestOffer, getBestListing.
    */
   async getOrder({
     side,
@@ -90,6 +95,7 @@ export class OrdersAPI {
 
   /**
    * Gets a list of orders from API based on query options.
+   * @deprecated Use collection-based endpoints instead: getAllOffers, getAllListings, getBestOffer, getBestListing.
    */
   async getOrders({
     side,
@@ -176,6 +182,7 @@ export class OrdersAPI {
 
   /**
    * Post an order to OpenSea.
+   * @deprecated Use postListing or postOffer instead.
    */
   async postOrder(
     order: ProtocolData,
@@ -216,6 +223,48 @@ export class OrdersAPI {
     return deserializeOrder(response.order);
   }
 
+  /**
+   * Post a listing to OpenSea. Returns the new Listing response format.
+   */
+  async postListing(
+    order: ProtocolData,
+    protocolAddress: string,
+  ): Promise<Listing> {
+    if (!order) {
+      throw new Error("order data is required");
+    }
+    if (!protocolAddress || !/^0x[a-fA-F0-9]{40}$/.test(protocolAddress)) {
+      throw new Error("Invalid protocol address format");
+    }
+
+    const response = await this.fetcher.post<ListingPostQueryResponse>(
+      getOrdersAPIPath(this.chain, "seaport", OrderSide.LISTING),
+      { ...order, protocol_address: protocolAddress },
+    );
+    return response.listing;
+  }
+
+  /**
+   * Post an offer to OpenSea. Returns the new Offer response format.
+   */
+  async postOffer(
+    order: ProtocolData,
+    protocolAddress: string,
+  ): Promise<Offer> {
+    if (!order) {
+      throw new Error("order data is required");
+    }
+    if (!protocolAddress || !/^0x[a-fA-F0-9]{40}$/.test(protocolAddress)) {
+      throw new Error("Invalid protocol address format");
+    }
+
+    const response = await this.fetcher.post<OfferPostQueryResponse>(
+      getOrdersAPIPath(this.chain, "seaport", OrderSide.OFFER),
+      { ...order, protocol_address: protocolAddress },
+    );
+    return response.offer;
+  }
+
   /**
    * Offchain cancel an order, offer or listing, by its order hash when protected by the SignedZone.
    */

src/orders/types.ts

@@ -1,5 +1,6 @@
 import { BasicOrderParametersStruct } from "@opensea/seaport-js/lib/typechain-types/seaport/contracts/Seaport";
 import { AdvancedOrder, OrderWithCounter } from "@opensea/seaport-js/lib/types";
+import { Listing, Offer } from "../api/types";
 import { OpenSeaAccount, OrderSide } from "../types";
 
 // Protocol data
@@ -173,4 +174,15 @@ export type OrdersQueryResponse = QueryCursors & {
   orders: SerializedOrderV2[];
 };
 
+/** @deprecated Use ListingPostQueryResponse or OfferPostQueryResponse instead. */
 export type OrdersPostQueryResponse = { order: SerializedOrderV2 };
+
+export type ListingPostQueryResponse = {
+  order: SerializedOrderV2;
+  listing: Listing;
+};
+
+export type OfferPostQueryResponse = {
+  order: SerializedOrderV2;
+  offer: Offer;
+};