opensea-js/src/api/collections.ts

TypeScript SDK for the OpenSea marketplace helps developers build new experiences using NFTs and our marketplace data

import {
  getCollectionPath,
  getCollectionsPath,
  getCollectionStatsPath,
  getTraitsPath,
} from "./apiPaths";
import { Fetcher } from "./fetcher";
import {
  GetCollectionResponse,
  GetCollectionsResponse,
  CollectionOrderByOption,
  GetCollectionsArgs,
  GetTraitsResponse,
} from "./types";
import { Chain, OpenSeaCollection, OpenSeaCollectionStats } from "../types";
import { collectionFromJSON } from "../utils/converters";

/**
 * Collection-related API operations
 */
export class CollectionsAPI {
  constructor(private fetcher: Fetcher) {}

  /**
   * Fetch an OpenSea collection.
   */
  async getCollection(slug: string): Promise<OpenSeaCollection> {
    const path = getCollectionPath(slug);
    const response = await this.fetcher.get<GetCollectionResponse>(path);
    return collectionFromJSON(response);
  }

  /**
   * Fetch a list of OpenSea collections.
   */
  async getCollections(
    orderBy: CollectionOrderByOption = CollectionOrderByOption.CREATED_DATE,
    chain?: Chain,
    creatorUsername?: string,
    includeHidden: boolean = false,
    limit?: number,
    next?: string,
  ): Promise<GetCollectionsResponse> {
    const path = getCollectionsPath();
    const args: GetCollectionsArgs = {
      order_by: orderBy,
      chain,
      creator_username: creatorUsername,
      include_hidden: includeHidden,
      limit,
      next,
    };
    const response = await this.fetcher.get<GetCollectionsResponse>(path, args);
    response.collections = response.collections.map((collection) =>
      collectionFromJSON(collection),
    );
    return response;
  }

  /**
   * Fetch stats for an OpenSea collection.
   */
  async getCollectionStats(slug: string): Promise<OpenSeaCollectionStats> {
    const path = getCollectionStatsPath(slug);
    const response = await this.fetcher.get<OpenSeaCollectionStats>(path);
    return response as OpenSeaCollectionStats;
  }

  /**
   * Fetch all traits for a collection with their possible values and counts.
   */
  async getTraits(collectionSlug: string): Promise<GetTraitsResponse> {
    const path = getTraitsPath(collectionSlug);
    const response = await this.fetcher.get<GetTraitsResponse>(path);
    return response;
  }
}