@opensea/sdk 9.0.0

package/src/utils/converters.ts

@@ -0,0 +1,145 @@
+import type {
+  Fee,
+  OpenSeaAccount,
+  OpenSeaCollection,
+  OpenSeaPaymentToken,
+  PricingCurrencies,
+  RarityStrategy,
+} from "../types"
+
+/**
+ * Converts a collection JSON response to an OpenSeaCollection object.
+ * @param collection The raw collection JSON from the API
+ * @returns OpenSeaCollection object
+ */
+export const collectionFromJSON = (collection: any): OpenSeaCollection => {
+  return {
+    name: collection.name,
+    collection: collection.collection,
+    description: collection.description,
+    imageUrl: collection.image_url,
+    bannerImageUrl: collection.banner_image_url,
+    owner: collection.owner,
+    safelistStatus: collection.safelist_status,
+    category: collection.category,
+    isDisabled: collection.is_disabled,
+    isNSFW: collection.is_nsfw,
+    traitOffersEnabled: collection.trait_offers_enabled,
+    collectionOffersEnabled: collection.collection_offers_enabled,
+    openseaUrl: collection.opensea_url,
+    projectUrl: collection.project_url,
+    wikiUrl: collection.wiki_url,
+    discordUrl: collection.discord_url,
+    telegramUrl: collection.telegram_url,
+    twitterUsername: collection.twitter_username,
+    instagramUsername: collection.instagram_username,
+    contracts: (collection.contracts ?? []).map((contract: any) => ({
+      address: contract.address,
+      chain: contract.chain,
+    })),
+    editors: collection.editors,
+    fees: (collection.fees ?? []).map(feeFromJSON),
+    rarity: rarityFromJSON(collection.rarity),
+    pricingCurrencies: pricingCurrenciesFromJSON(collection.pricing_currencies),
+    totalSupply: collection.total_supply,
+    uniqueItemCount: collection.unique_item_count,
+    createdDate: collection.created_date,
+    requiredZone: collection.required_zone,
+  }
+}
+
+/**
+ * Converts a rarity JSON response to a RarityStrategy object.
+ * @param rarity The raw rarity JSON from the API
+ * @returns RarityStrategy object or null
+ */
+export const rarityFromJSON = (rarity: any): RarityStrategy | null => {
+  if (!rarity) {
+    return null
+  }
+  const fromJSON: RarityStrategy = {
+    strategyId: rarity.strategy_id,
+    strategyVersion: rarity.strategy_version,
+    calculatedAt: rarity.calculated_at,
+    maxRank: rarity.max_rank,
+    tokensScored: rarity.tokens_scored,
+  }
+  return fromJSON
+}
+
+/**
+ * Converts a payment token JSON response to an OpenSeaPaymentToken object.
+ * @param token The raw payment token JSON from the API
+ * @returns OpenSeaPaymentToken object
+ */
+export const paymentTokenFromJSON = (token: any): OpenSeaPaymentToken => {
+  const fromJSON: OpenSeaPaymentToken = {
+    name: token.name,
+    symbol: token.symbol,
+    decimals: token.decimals,
+    address: token.address,
+    chain: token.chain,
+    imageUrl: token.image,
+    ethPrice: token.eth_price,
+    usdPrice: token.usd_price,
+  }
+  return fromJSON
+}
+
+/**
+ * Converts a pricing currencies JSON response to a PricingCurrencies object.
+ * @param pricingCurrencies The raw pricing currencies JSON from the API
+ * @returns PricingCurrencies object or undefined
+ */
+export const pricingCurrenciesFromJSON = (
+  pricingCurrencies: any,
+): PricingCurrencies | undefined => {
+  if (!pricingCurrencies) {
+    return undefined
+  }
+  return {
+    listingCurrency: pricingCurrencies.listing_currency
+      ? paymentTokenFromJSON(pricingCurrencies.listing_currency)
+      : undefined,
+    offerCurrency: pricingCurrencies.offer_currency
+      ? paymentTokenFromJSON(pricingCurrencies.offer_currency)
+      : undefined,
+  }
+}
+
+/**
+ * Converts an account JSON response to an OpenSeaAccount object.
+ * @param account The raw account JSON from the API
+ * @returns OpenSeaAccount object
+ */
+export const accountFromJSON = (account: any): OpenSeaAccount => {
+  return {
+    address: account.address,
+    username: account.username,
+    profileImageUrl: account.profile_image_url,
+    bannerImageUrl: account.banner_image_url,
+    website: account.website,
+    socialMediaAccounts: (account.social_media_accounts ?? []).map(
+      (acct: any) => ({
+        platform: acct.platform,
+        username: acct.username,
+      }),
+    ),
+    bio: account.bio,
+    joinedDate: account.joined_date,
+  }
+}
+
+/**
+ * Converts a fee JSON response to a Fee object.
+ * @param fee The raw fee JSON from the API
+ * @returns Fee object
+ */
+export const feeFromJSON = (fee: any): Fee => {
+  const fromJSON: Fee = {
+    fee: fee.fee,
+    recipient: fee.recipient,
+    required: fee.required,
+  }
+  return fromJSON
+}

package/src/utils/dateHelper.ts

@@ -0,0 +1,48 @@
+/**
+ * Utility functions for working with Unix timestamps (seconds since epoch).
+ * OpenSea API and Seaport protocol use Unix timestamps in seconds, not milliseconds.
+ */
+
+/**
+ * Get the current Unix timestamp in seconds
+ * @returns Current time as Unix timestamp (seconds since epoch)
+ */
+export function getCurrentUnixTimestamp(): number {
+  return Math.floor(Date.now() / 1000)
+}
+
+/**
+ * Get a Unix timestamp for a future time
+ * @param seconds Number of seconds from now
+ * @returns Unix timestamp (seconds since epoch)
+ * @example
+ * // Get timestamp for 1 day from now
+ * const tomorrow = getUnixTimestampInSeconds(60 * 60 * 24);
+ */
+export function getUnixTimestampInSeconds(seconds: number): number {
+  return getCurrentUnixTimestamp() + seconds
+}
+
+/**
+ * Common time durations in seconds for convenience
+ */
+export enum TimeInSeconds {
+  /** 1 minute = 60 seconds */
+  MINUTE = 60,
+  /** 1 hour = 3600 seconds */
+  HOUR = 3600,
+  /** 1 day = 86400 seconds */
+  DAY = 86400,
+  /** 1 week = 604800 seconds */
+  WEEK = 604800,
+  /** 30 days = 2592000 seconds */
+  MONTH = 2592000,
+}
+
+/**
+ * Get Unix timestamp for one month from now (30 days)
+ * @returns Unix timestamp (seconds since epoch) for 30 days in the future
+ */
+export const oneMonthFromNowInSeconds = (): number => {
+  return getUnixTimestampInSeconds(TimeInSeconds.MONTH)
+}

package/src/utils/fees.ts

@@ -0,0 +1,31 @@
+import { FixedNumber } from "ethers"
+import { FIXED_NUMBER_100 } from "../constants"
+import type { Fee } from "../types"
+
+/**
+ * Sums up the basis points for fees.
+ * @param fees The fees to sum up
+ * @returns sum of basis points
+ */
+export const totalBasisPointsForFees = (fees: Fee[]): bigint => {
+  const feeBasisPoints = fees.map(fee => basisPointsForFee(fee))
+  const totalBasisPoints = feeBasisPoints.reduce(
+    (sum, basisPoints) => basisPoints + sum,
+    0n,
+  )
+  return totalBasisPoints
+}
+
+/**
+ * Converts a fee to its basis points representation.
+ * @param fee The fee to convert
+ * @returns the basis points
+ */
+export const basisPointsForFee = (fee: Fee): bigint => {
+  return BigInt(
+    FixedNumber.fromString(fee.fee.toString())
+      .mul(FIXED_NUMBER_100)
+      .toFormat(0) // format to 0 decimal places to convert to bigint
+      .toString(),
+  )
+}

package/src/utils/index.ts

@@ -0,0 +1,2 @@
+export * from "./dateHelper"
+export * from "./utils"

package/src/utils/protocol.ts

@@ -0,0 +1,185 @@
+import type { Seaport } from "@opensea/seaport-js"
+import {
+  CROSS_CHAIN_SEAPORT_V1_6_ADDRESS,
+  ItemType,
+} from "@opensea/seaport-js/lib/constants"
+import { ethers } from "ethers"
+import {
+  ALTERNATE_SEAPORT_V1_6_ADDRESS,
+  SHARED_STOREFRONT_ADDRESSES,
+  SHARED_STOREFRONT_LAZY_MINT_ADAPTER_CROSS_CHAIN_ADDRESS,
+} from "../constants"
+import type { TokenStandard } from "../types"
+
+// Pre-compute checksummed protocol addresses for consistent comparisons
+const VALID_PROTOCOL_ADDRESSES = new Set([
+  ethers.getAddress(CROSS_CHAIN_SEAPORT_V1_6_ADDRESS),
+  ethers.getAddress(ALTERNATE_SEAPORT_V1_6_ADDRESS),
+])
+
+/**
+ * Gets the appropriate ItemType for a given token standard.
+ * @param tokenStandard The token standard (ERC20, ERC721, ERC1155)
+ * @returns The corresponding ItemType from Seaport
+ */
+export const getAssetItemType = (tokenStandard: TokenStandard) => {
+  const normalizedStandard = tokenStandard.toUpperCase()
+  switch (normalizedStandard) {
+    case "ERC20":
+      return ItemType.ERC20
+    case "ERC721":
+      return ItemType.ERC721
+    case "ERC1155":
+      return ItemType.ERC1155
+    default:
+      throw new Error(`Unknown schema name: ${tokenStandard}`)
+  }
+}
+
+/**
+ * Remaps shared storefront token addresses to the lazy mint adapter address.
+ *
+ * OpenSea's shared storefront contracts require special handling - when a token
+ * is from a shared storefront address, it must be remapped to the lazy mint
+ * adapter address for proper Seaport order creation.
+ *
+ * @param tokenAddress The token contract address to check
+ * @returns The lazy mint adapter address if the input is a shared storefront address,
+ *          otherwise returns the original address unchanged
+ */
+export const remapSharedStorefrontAddress = (tokenAddress: string): string => {
+  if (SHARED_STOREFRONT_ADDRESSES.has(tokenAddress.toLowerCase())) {
+    return ethers.getAddress(
+      SHARED_STOREFRONT_LAZY_MINT_ADAPTER_CROSS_CHAIN_ADDRESS,
+    )
+  }
+  return tokenAddress
+}
+
+/**
+ * Returns if a protocol address is valid.
+ * @param protocolAddress The protocol address
+ */
+export const isValidProtocol = (protocolAddress: string): boolean => {
+  try {
+    return VALID_PROTOCOL_ADDRESSES.has(ethers.getAddress(protocolAddress))
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Throws an error if the protocol address is not valid.
+ * @param protocolAddress The protocol address
+ */
+export const requireValidProtocol = (protocolAddress: string) => {
+  if (!isValidProtocol(protocolAddress)) {
+    throw new Error(`Unsupported protocol address: ${protocolAddress}`)
+  }
+}
+
+/**
+ * Get the Seaport instance for a given protocol address.
+ * This is a shared utility to avoid duplicating the logic across multiple SDK manager classes.
+ * @param protocolAddress The protocol address
+ * @param seaport The Seaport instance
+ * @returns The Seaport instance for the given protocol address
+ * @throws Error if the protocol address is not supported
+ */
+export const getSeaportInstance = (
+  protocolAddress: string,
+  seaport: Seaport,
+): Seaport => {
+  requireValidProtocol(protocolAddress)
+  return seaport
+}
+
+/**
+ * Get the Seaport version string for a given protocol address.
+ * @param protocolAddress The protocol address
+ * @returns The version string (e.g., "1.6")
+ * @throws Error if the protocol address is not supported
+ */
+export const getSeaportVersion = (protocolAddress: string): string => {
+  requireValidProtocol(protocolAddress)
+  return "1.6"
+}
+
+/**
+ * Decodes an encoded string of token IDs into an array of individual token IDs using bigint for precise calculations.
+ *
+ * The encoded token IDs can be in the following formats:
+ * 1. Single numbers: '123' => ['123']
+ * 2. Comma-separated numbers: '1,2,3,4' => ['1', '2', '3', '4']
+ * 3. Ranges of numbers: '5:8' => ['5', '6', '7', '8']
+ * 4. Combinations of single numbers and ranges: '1,3:5,8' => ['1', '3', '4', '5', '8']
+ * 5. Wildcard '*' (matches all token IDs): '*' => ['*']
+ *
+ * @param encodedTokenIds - The encoded string of token IDs to be decoded.
+ * @returns An array of individual token IDs after decoding the input.
+ *
+ * @throws {Error} If the input is not correctly formatted or if bigint operations fail.
+ *
+ * @example
+ * const encoded = '1,3:5,8';
+ * const decoded = decodeTokenIds(encoded); // Output: ['1', '3', '4', '5', '8']
+ *
+ * @example
+ * const encodedWildcard = '*';
+ * const decodedWildcard = decodeTokenIds(encodedWildcard); // Output: ['*']
+ *
+ * @example
+ * const emptyEncoded = '';
+ * const decodedEmpty = decodeTokenIds(emptyEncoded); // Output: []
+ */
+export const decodeTokenIds = (encodedTokenIds: string): string[] => {
+  if (encodedTokenIds === "*") {
+    return ["*"]
+  }
+
+  if (encodedTokenIds === "") {
+    return []
+  }
+
+  // Check for whitespace and provide helpful error message
+  if (/\s/.test(encodedTokenIds)) {
+    throw new Error(
+      "Invalid input format: whitespace is not allowed. Expected format: '1,2,3' or '1:5' or '1,3:5,8' (no spaces).",
+    )
+  }
+
+  const validFormatRegex = /^(\d+(:\d+)?)(,\d+(:\d+)?)*$/
+
+  if (!validFormatRegex.test(encodedTokenIds)) {
+    throw new Error(
+      "Invalid input format. Expected a valid comma-separated list of numbers and ranges.",
+    )
+  }
+
+  const ranges = encodedTokenIds.split(",")
+  const tokenIds: string[] = []
+
+  for (const range of ranges) {
+    if (range.includes(":")) {
+      const [startStr, endStr] = range.split(":")
+      const start = BigInt(startStr)
+      const end = BigInt(endStr)
+      const diff = end - start + 1n
+
+      if (diff <= 0) {
+        throw new Error(
+          `Invalid range. End value: ${end} must be greater than or equal to the start value: ${start}.`,
+        )
+      }
+
+      for (let i = 0n; i < diff; i += 1n) {
+        tokenIds.push((start + i).toString())
+      }
+    } else {
+      const tokenId = BigInt(range)
+      tokenIds.push(tokenId.toString())
+    }
+  }
+
+  return tokenIds
+}

package/src/utils/rateLimit.ts

@@ -0,0 +1,147 @@
+import type { OpenSeaRateLimitError } from "../types"
+import { pluralize } from "./stringHelper"
+
+/**
+ * Default configuration for rate limit handling
+ */
+const DEFAULT_MAX_RETRIES = 3
+const DEFAULT_BASE_RETRY_DELAY_MS = 1000
+const EXPONENTIAL_BACKOFF_BASE = 2
+const MILLISECONDS_PER_SECOND = 1000
+
+/**
+ * HTTP status codes that indicate rate limiting
+ */
+const RATE_LIMIT_STATUS_CODE = 429
+const CUSTOM_RATE_LIMIT_STATUS_CODE = 599
+
+/**
+ * Options for handling rate-limited operations with retries.
+ * This is exported for SDK consumers who may want to use executeWithRateLimit
+ * for their own OpenSea API integrations.
+ */
+export interface RateLimitOptions {
+  /** Logger function for logging progress */
+  logger?: (message: string) => void
+  /** Maximum number of retry attempts for rate limit errors */
+  maxRetries?: number
+  /** Base delay in ms to wait after a rate limit error if retry-after header is not present */
+  baseRetryDelay?: number
+}
+
+/**
+ * Sleep for a specified duration
+ * @param ms Duration in milliseconds
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+/**
+ * Execute an async operation with automatic retry on rate limit errors.
+ * Respects the retry-after header when present, otherwise uses exponential backoff.
+ *
+ * @param operation The async operation to execute
+ * @param options Configuration for rate limit handling
+ * @returns The result of the operation
+ * @throws The last error encountered if all retries are exhausted
+ */
+export async function executeWithRateLimit<T>(
+  operation: () => Promise<T>,
+  options: RateLimitOptions = {},
+): Promise<T> {
+  const {
+    logger = () => {},
+    maxRetries = DEFAULT_MAX_RETRIES,
+    baseRetryDelay = DEFAULT_BASE_RETRY_DELAY_MS,
+  } = options
+
+  let lastError: Error | undefined
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await operation()
+    } catch (error) {
+      lastError = error as Error
+      const rateLimitError = error as OpenSeaRateLimitError
+
+      // Check if this is a rate limit error by status code (robust) or retry-after header
+      const isRateLimitError =
+        rateLimitError.statusCode === RATE_LIMIT_STATUS_CODE ||
+        rateLimitError.statusCode === CUSTOM_RATE_LIMIT_STATUS_CODE ||
+        rateLimitError.retryAfter !== undefined
+
+      if (!isRateLimitError || attempt === maxRetries) {
+        // Not a rate limit error or out of retries, throw the error
+        throw error
+      }
+
+      // Calculate delay
+      let delayMs: number
+      if (rateLimitError.retryAfter !== undefined) {
+        delayMs = rateLimitError.retryAfter * MILLISECONDS_PER_SECOND
+        logger(
+          `Rate limit hit. Waiting ${rateLimitError.retryAfter} seconds before retry (attempt ${attempt + 1}/${maxRetries})...`,
+        )
+      } else {
+        // Exponential backoff
+        delayMs = baseRetryDelay * EXPONENTIAL_BACKOFF_BASE ** attempt
+        const delaySeconds = delayMs / MILLISECONDS_PER_SECOND
+        logger(
+          `Rate limit hit. Waiting ${delaySeconds} seconds before retry (attempt ${attempt + 1}/${maxRetries})...`,
+        )
+      }
+
+      await sleep(delayMs)
+      logger(`Retrying operation...`)
+    }
+  }
+
+  // Should never reach here, but TypeScript needs this
+  throw lastError
+}
+
+/**
+ * Execute an array of async operations sequentially with rate limit handling.
+ * Logs progress after each operation.
+ *
+ * @param operations Array of async operations to execute
+ * @param options Configuration for rate limit handling and progress logging
+ * @returns Array of results from each operation
+ */
+export async function executeSequentialWithRateLimit<T>(
+  operations: Array<() => Promise<T>>,
+  options: RateLimitOptions & {
+    operationName?: string
+  } = {},
+): Promise<T[]> {
+  const {
+    logger = () => {},
+    operationName = "operation",
+    ...rateLimitOptions
+  } = options
+
+  const results: T[] = []
+  const total = operations.length
+
+  logger(`Starting ${total} ${pluralize(total, operationName)}...`)
+
+  for (let i = 0; i < operations.length; i++) {
+    const operation = operations[i]
+    logger(`Executing ${operationName} ${i + 1}/${total}...`)
+
+    const result = await executeWithRateLimit(operation, {
+      ...rateLimitOptions,
+      logger,
+    })
+
+    results.push(result)
+    logger(`Completed ${operationName} ${i + 1}/${total}`)
+  }
+
+  logger(
+    `All ${total} ${pluralize(total, operationName)} completed successfully`,
+  )
+
+  return results
+}

package/src/utils/stringHelper.ts

@@ -0,0 +1,25 @@
+/**
+ * Utility functions for string formatting and manipulation.
+ */
+
+/**
+ * Pluralizes a word based on count.
+ *
+ * @param count The number of items
+ * @param singular The singular form of the word
+ * @param plural Optional custom plural form. If not provided, adds 's' to singular
+ * @returns The appropriately pluralized word
+ *
+ * @example
+ * pluralize(1, 'listing') // 'listing'
+ * pluralize(5, 'listing') // 'listings'
+ * pluralize(1, 'query', 'queries') // 'query'
+ * pluralize(3, 'query', 'queries') // 'queries'
+ */
+export function pluralize(
+  count: number,
+  singular: string,
+  plural?: string,
+): string {
+  return count === 1 ? singular : plural || `${singular}s`
+}

package/src/utils/utils.ts

@@ -0,0 +1,36 @@
+import type { ethers } from "ethers"
+
+export * from "./chain"
+// Re-export all utilities from specialized modules
+export * from "./converters"
+export * from "./fees"
+export * from "./protocol"
+
+/**
+ * Estimate gas usage for a transaction.
+ * @param provider The Provider
+ * @param from Address sending transaction
+ * @param to Destination contract address
+ * @param data Data to send to contract
+ * @param value Value in ETH to send with data
+ */
+export async function estimateGas(
+  provider: ethers.Provider,
+  { from, to, data, value = 0n }: ethers.Transaction,
+) {
+  return await provider.estimateGas({
+    from,
+    to,
+    value: value.toString(),
+    data,
+  })
+}
+
+interface ErrorWithCode extends Error {
+  code: string
+}
+
+export const hasErrorCode = (error: unknown): error is ErrorWithCode => {
+  const untypedError = error as Partial<ErrorWithCode>
+  return !!untypedError.code
+}