@xoxno/sdk-js 0.0.1

package/src/nft/__tests__/nft.test.ts

@@ -0,0 +1,84 @@
+import { NFTModule } from '../index';
+import { APIClient } from '../../utils/api';
+import { OrderByTradingActivity } from '../../types';
+
+describe('NFTModule', () => {
+  let nftModule: NFTModule;
+  const inputIdentifier = 'BANANA-e955fd-01';
+  const collection = 'BANANA-e955fd';
+  const nonce = 1;
+  const nonceHex = '01';
+  beforeAll(() => {
+    APIClient.init();
+    nftModule = new NFTModule();
+  });
+
+  it('should return NFT data when given a valid identifier', async () => {
+    const nftData = await nftModule.getNFTByIdentifier(inputIdentifier);
+    expect(nftData).toBeDefined();
+    expect(nftData.identifier).toEqual(inputIdentifier);
+  });
+
+  it('should return NFT data when given a valid collection and nonce', async () => {
+    const nftData = await nftModule.getNFTByCollectionAndNonce(
+      collection,
+      nonce
+    );
+    expect(nftData).toBeDefined();
+    expect(nftData.identifier).toEqual(inputIdentifier);
+  });
+
+  it('should return NFT data when given a valid collection and nonce as hex', async () => {
+    const nftData = await nftModule.getNFTByCollectionAndNonceHex(
+      collection,
+      nonceHex
+    );
+    expect(nftData).toBeDefined();
+    expect(nftData.identifier).toEqual(inputIdentifier);
+  });
+
+  it('should return empty NFT trading activity', async () => {
+    const nftTradingActivity = await nftModule.getTradingActivity({
+      identifiers: [inputIdentifier],
+    });
+    expect(nftTradingActivity).toBeDefined();
+    expect(nftTradingActivity.empty).toEqual(true);
+  });
+
+  it('should return NFT trading activity', async () => {
+    const nftTradingActivity = await nftModule.getTradingActivity({
+      identifiers: ['BANANA-e955fd-05d9'],
+      orderBy: [OrderByTradingActivity.OldestPlaced],
+      top: 1,
+    });
+    expect(nftTradingActivity).toBeDefined();
+    expect(nftTradingActivity.empty).toEqual(false);
+    expect(nftTradingActivity.resources.length).toEqual(1);
+    expect(nftTradingActivity.resources[0]).toMatchObject({
+      txHash:
+        'f2cc0f9abbe6e18855cec144cecee5a6e7e0fdf2249a7e2b487935c4630aec3d',
+      collection: 'BANANA-e955fd',
+      identifier: 'BANANA-e955fd-05d9',
+      timestamp: 1642523586,
+      action: 'buy',
+      price: 0.1,
+      paymentToken: 'EGLD',
+      buyer: 'erd1ecae8gpcsf5fk9na69my54c4t3dw27pdgk009huaj0ekjcp02u4qtw9e9d',
+      seller: 'erd1kkp6kcs5qpmfmcs4vj4v07kq750anpdz579mh2962r2suum2hfjsfrdaav',
+      usdPrice: 17.24,
+      egldValue: 0.1,
+      name: 'Banana #1497',
+      url: 'https://media.elrond.com/nfts/asset/QmZzdYmNtQw5F8WGY4eFmyqcFcziPa73DMSypMJWTxRdqa/1337.png',
+      avifUrl:
+        'https://trustmarket.blob.core.windows.net/nftmedia/BANANA-e955fd/BANANA-e955fd-05d9.avif',
+      webpUrl:
+        'https://trustmarket.blob.core.windows.net/nftmedia/BANANA-e955fd/BANANA-e955fd-05d9.webp',
+      rank: 480,
+      marketplace: 'XO',
+      id: '4505a7ae-eab9-4591-9f81-81671e63a9a3',
+      _ts: 1677342781,
+      sellerUsername: '@denysvicol',
+      buyerUsername: '@stefanmorar',
+    });
+  });
+});

package/src/nft/index.ts

@@ -0,0 +1,98 @@
+import { NftData } from '../types/nft';
+import { TradingActivityResponse, TradincActivityArgs } from '../types/trading';
+import { APIClient } from '../utils/api';
+import { getActivity } from '../utils/getActivity';
+import { getIdentifierFromColAndNonce } from '../utils/helpers';
+import { isValidCollectionTicker, isValidNftIdentifier } from '../utils/regex';
+
+/**
+ * NFTModule provides a set of methods to interact with single NFTs.
+ * It includes methods for getting single NFT information, and searching NFTs by collection and nonce.
+ *
+ * @example
+ * const xoxno = new XOXNO({ apiURL: 'https://api.xoxno.com', apiKey: 'your-api-key' });
+ * const nftModule = xoxno.nft;
+ */
+
+export class NFTModule {
+  private api: APIClient;
+  constructor() {
+    this.api = APIClient.getClient();
+  }
+
+  /**
+   * Get the NFT data for the specified identifier.
+   * @param identifier The NFT identifier. Must be a valid NFT identifier.
+   * @returns {Promise<NftData>} The NFT data.
+   */
+  public getNFTByIdentifier = async (identifier: string): Promise<NftData> => {
+    if (!isValidNftIdentifier(identifier)) {
+      throw new Error('Invalid identifier: ' + identifier);
+    }
+    const response = await this.api.fetchWithTimeout<NftData>(
+      `/nfts/${identifier}`
+    );
+    return response;
+  };
+
+  /**
+   * Gets an NFT by collection and nonce.
+   * @param collection The collection ticker.
+   * @param nonce The nonce of the NFT.
+   * @returns {Promise<NftData>} The NFT data.
+   * @throws Throws an error when the collection ticker is invalid.
+   */
+  public getNFTByCollectionAndNonce = async (
+    collection: string,
+    nonce: number
+  ): Promise<NftData> => {
+    if (!isValidCollectionTicker(collection)) {
+      throw new Error('Invalid collection ticker: ' + collection);
+    }
+
+    const response = await this.api.fetchWithTimeout<NftData>(
+      `/nfts/${getIdentifierFromColAndNonce(collection, nonce)}`
+    );
+    return response;
+  };
+
+  /**
+   * Get NFT by collection and nonce hex
+   *
+   * @param collection - collection ticker
+   * @param nonceHex - nonce hex
+   * @return {Promise<NftData>} NFT data
+   */
+
+  public getNFTByCollectionAndNonceHex = async (
+    collection: string,
+    nonceHex: string
+  ): Promise<NftData> => {
+    // check that collection is valid
+    if (!isValidCollectionTicker(collection)) {
+      throw new Error('Invalid collection ticker: ' + collection);
+    }
+    // make sure nonceHex is even
+    if (nonceHex.length % 2 !== 0) {
+      nonceHex = '0' + nonceHex;
+    }
+    // fetch the NFT data
+    const response = await this.api.fetchWithTimeout<NftData>(
+      `/nfts/${[collection, nonceHex].join('-')}`
+    );
+    return response;
+  };
+
+  /**
+   * Retrieves trading history based on the provided arguments.
+   *
+   * @param {TradincActivityArgs} args - The arguments for filtering the trading activity.
+   * @returns {Promise<TradingActivityResponse>} A promise resolving to a TradingActivityResponse object containing the activity.
+   * @throws {Error} Throws an error if the 'top' argument is greater than 35.
+   */
+  public getTradingActivity = async (
+    args: TradincActivityArgs
+  ): Promise<TradingActivityResponse> => {
+    return await getActivity(args, this.api);
+  };
+}

package/src/types/collection.d.ts

@@ -0,0 +1,267 @@
+import { NftData } from './nft';
+
+export interface ISocials {
+  twitter: string;
+  instagram: string;
+  website: string;
+  telegram: string;
+  discord: string;
+  facebook: string;
+  youtube: string;
+}
+
+export interface IMintInfo {
+  contractAddress: string;
+  totalNftMinted: number;
+  collectionTag: string;
+  cid: string;
+  mediaType: string;
+  collectionSize: number;
+  nftTransferLimited: string;
+  allowsPublicBurn: string;
+  kycRequired: string;
+  allowsRefund: string;
+  hasReveal: string;
+}
+
+export interface ICollectionProfile {
+  dataType: 'collectionProfile';
+  collection: string;
+  name: string;
+  description: string;
+  isVisible: boolean;
+  isVerified: boolean;
+  profile: string;
+  banner: string;
+  statistics: {
+    tradeData: {
+      dayEgldVolume: number;
+      weekEgldVolume: number;
+      totalEgldVolume: number;
+      averageEgldPrice: number;
+      athEgldPrice: number;
+      athTxHash: string;
+      totalTrades: number;
+    };
+    mintData: {
+      totalMintEgldVolume: number;
+      weekMintEgldVolume: number;
+      dayMintEgldVolume: number;
+    };
+    other: {
+      nftCount: number;
+      followCount: number;
+      holdersCount?: number;
+    };
+  };
+  owner: string;
+  creator: string;
+  isMintable: boolean;
+  mintInfo: IMintInfo;
+  mintStages: {
+    name: string;
+    collectionTag: string;
+    mintEnabled: boolean;
+    isWhitelist: boolean;
+    startTime: number;
+    endTime: number;
+    mintLimit: number;
+    mintCount: number;
+    prices: {
+      tokenIdentifier: string;
+      tokenNonce: string;
+      amount: string;
+    }[];
+    walletLimit: number;
+  }[];
+  hasStaking: boolean;
+  id: string;
+  socials: ISocials;
+  type: string;
+  lastVerifiedTimestamp: number;
+  lastVerifiedBy: string;
+  _ts: number;
+}
+
+export interface AttributeData {
+  attributeOccurrence: number;
+  FloorPrice: number;
+  OnSale: number;
+}
+
+export interface MetadataAttribute {
+  trait_type: string;
+  value: string;
+}
+
+export interface TraitValues {
+  [traitValue: string]: AttributeData;
+}
+
+export interface ICollectionAttributes {
+  [traitType: string]: TraitValues;
+}
+export enum Marketplace {
+  XO = 'XO',
+  FM = 'FM',
+  DR = 'DR',
+  KG = 'KG',
+}
+
+export interface GlobalOffer {
+  attributes: MetadataAttribute[];
+  collection: string;
+  isActive: boolean;
+  marketplace: string;
+  offer_id: number;
+  owner: string;
+  ownerProfile?: string;
+  ownerUsername?: string;
+  payment_nonce: number;
+  payment_token: string;
+  price: string;
+  quantity: number;
+  short_price: number;
+  timestamp: number;
+}
+
+export const enum FieldsToSelect {
+  Rank = 'metadata/rarity/rank',
+  Attributes = 'metadata/attributes',
+  Description = 'metadata/description',
+  Name = 'name',
+  OnSale = 'onSale',
+  SaleInfo = 'saleInfoNft',
+  Royalties = 'royalties',
+  Identifier = 'identifier',
+  Collection = 'collection',
+  OriginalURL = 'url',
+  Nonce = 'nonce',
+  ContentType = 'originalMedia/contentType',
+  WasProcessed = 'wasProcessed',
+  AvifURL = 'avifUrl',
+  WebpURL = 'webpUrl',
+  Type = 'type',
+}
+
+export const enum SearchOrderBy {
+  PriceHighToLow = 'saleInfoNft/min_bid_short desc',
+  PriceLowToHigh = 'saleInfoNft/min_bid_short asc',
+  RarityHighToLow = 'metadata/rarity/rank desc',
+  RarityLowToHigh = 'metadata/rarity/rank asc',
+  NonceHighToLow = 'nonce desc',
+  NonceLowToHigh = 'nonce asc',
+  RecentListed = 'saleInfoNft/timestamp desc',
+  OldestListed = 'saleInfoNft/timestamp asc',
+}
+
+export interface Filter {
+  marketplace?: Marketplace[];
+  onSale?: boolean;
+  auctionTypes?: string[];
+  tokens?: string[];
+  attributes?: MetadataAttribute[];
+  range?: {
+    min: number;
+    max: number;
+    type: string;
+  };
+  rankRange?: {
+    min?: number;
+    max?: number;
+  };
+  levelRange?: {
+    min?: number;
+    max?: number;
+  };
+}
+
+export interface SearchNFTs {
+  filters: Filter;
+  name?: string;
+  orderBy?: SearchOrderBy[];
+  collection: string;
+  top: number;
+  skip: number;
+  select?: FieldsToSelect[];
+}
+
+export interface SearchNFTsArgs {
+  /**  The collection to search in */
+  collection: string;
+  /** If true, will return only NFTs that are on sale */
+  onlyOnSale?: boolean;
+  /** If true, will return only NFTs that are on auction */
+  onlyAuctions?: boolean;
+  /** If set, will return only NFTs with a price in the specified range */
+  priceRange?: {
+    min: number;
+    max: number;
+  };
+  /** If set, will return only NFTs listed in the specified tokens */
+  listedInToken?: string[];
+  /** If set, will return only NFTs with a rank in the specified range */
+  rankRange?: {
+    min: number;
+    max: number;
+  };
+  /** If set, will return only NFTs with a cantina level in the specified range */
+  cantinaLevelRange?: {
+    min: number;
+    max: number;
+  };
+  /** If set, will return only NFTs with a name that contains the specified string */
+  searchName?: string;
+  /** The number of results to return */
+  top?: number;
+  /** The order by to use */
+  skip?: number;
+  /** The order of the results based on a field */
+  orderBy?: SearchOrderBy[];
+  /** If set, will return only the specified fields */
+  onlySelectFields?: FieldsToSelect[];
+  /** If set, will return only NFTs listed in the specified marketplaces */
+  listedOnlyOn?: Marketplace[];
+  /** If set, will return only NFTs with the specified attributes */
+  attributes?: MetadataAttribute[];
+}
+
+export interface SearchNFTsResponse {
+  /** The total count of the results for the specific query */
+  count: number;
+  /** The results count for the current page */
+  resultsCount: number;
+  /** The results for the current page */
+  results: NftData[];
+  /** If the results are empty */
+  empty: boolean;
+  /** The payload to use to get the next page */
+  getNextPagePayload: SearchNFTsArgs;
+  /** If there are more results to fetch */
+  hasMoreResults: boolean;
+}
+
+export interface TradingActivity {
+  action: string;
+  attributes: MetadataAttribute[];
+  avifUrl: string;
+  buyer: string;
+  buyerUsername: string;
+  collection: string;
+  egldValue: number;
+  id: string;
+  identifier: string;
+  marketplace: Marketplace;
+  name: string;
+  paymentToken: string;
+  price: number;
+  rank: number;
+  seller: string;
+  sellerUsername: string;
+  timestamp: number;
+  txHash: string;
+  url: string;
+  usdPrice: number;
+  webpUrl: string;
+  _ts: number;
+}

package/src/types/index.ts

@@ -0,0 +1,3 @@
+export * from './collection';
+export * from './nft';
+export * from './trading';

package/src/types/interactions.d.ts

@@ -0,0 +1,16 @@
+type Offer = {
+  offer_id: number;
+  collection: string;
+  quantity: number;
+  payment_token: string;
+  payment_nonce: number;
+  price: number;
+  timestamp: number;
+  owner: string;
+  attributes: Array<{
+    trait_type: string;
+    value: string;
+  }>;
+  new_version: boolean;
+  price_long: string;
+};

package/src/types/nft.d.ts

@@ -0,0 +1,100 @@
+export interface NFTAttribute {
+  trait_type: string;
+  value: string;
+  occurance: number;
+  rarity: number;
+  frequency: number;
+  OnSale?: number;
+  FloorPrice?: number;
+}
+
+export interface NFTMetadata {
+  description?: string;
+  attributes: NFTAttribute[];
+  rarity: {
+    rank: number;
+  };
+}
+
+export interface OriginalMedia {
+  contentType: string;
+  contentLength: number;
+}
+
+export interface SaleInfoNft {
+  auction_id: number;
+  seller: string;
+  current_winner: string;
+  min_bid: string;
+  max_bid: string;
+  current_bid: string;
+  start_time: number;
+  deadline: number;
+  accepted_payment_token: string;
+  accepted_payment_token_nonce: number;
+  auction_type: string;
+  timestamp: number;
+  min_bid_short: number;
+  max_bid_short: number;
+  current_bid_short: number;
+  quantity: null | number;
+  marketplace: string;
+  usd: string;
+  usd_max_bid: string;
+}
+
+export interface NftValue {
+  floorValue: number;
+  avgValue: number;
+  maxValue: number;
+  collectionFp: number;
+}
+
+export interface GameData {
+  name: string;
+  value: number;
+}
+
+export interface OffersInfo {
+  EgldValue: number;
+  UsdValue: number;
+  deadline: number;
+  isActive: boolean;
+  offer_id: number;
+  owner: string;
+  ownerUsername: string;
+  payment_nonce: number;
+  payment_token: string;
+  price: string;
+  price_short: number;
+  quantity: number;
+  timestamp: number;
+}
+
+export interface NftData {
+  identifier: string;
+  collection: string;
+  attributes?: string;
+  nonce: number;
+  type: string;
+  name: string;
+  creator?: string;
+  royalties: number;
+  url: string;
+  avifUrl: string;
+  webpUrl: string;
+  wasProcessed: boolean;
+  onSale: boolean;
+  hasOffers?: boolean;
+  metadata: Metadata;
+  originalMedia: OriginalMedia;
+  saleInfoNft: SaleInfoNft;
+  offersInfo: OffersInfo[];
+  gameData: GameData[]; // Only for Cantina Rolaye
+  owner?: string;
+  ownerCount?: number; // Only for SFTs with over 1 owner
+  ownerUsername?: string;
+  isVerified: boolean;
+  isVisible: boolean;
+  nftValue?: NftValue;
+}

package/src/types/trading.d.ts

@@ -0,0 +1,95 @@
+import { Marketplace, MetadataAttribute } from './collection';
+
+export interface TradingActivityQueryFilter {
+  filters: {
+    collection?: string[];
+    identifier?: string[];
+    address?: string[];
+    tokens?: string[];
+    marketplace?: Marketplace[];
+    action?: string[];
+    range?: {
+      min: number;
+      max: number;
+    };
+    rankRange?: {
+      min: number;
+      max: number;
+    };
+    timestampRange?: {
+      min: number;
+      max: number;
+    };
+    attributes?: MetadataAttribute[];
+  };
+  top: number;
+  skip: number;
+  select?: SelectFieldsTradingActivity[];
+  orderBy?: OrderByTradingActivity[];
+}
+export interface TradincActivityArgs {
+  /** The collections to fetch the trading activity from */
+  collections?: string[];
+  /** The identifier of the NFTs to fetch the trading activity from */
+  identifiers?: string[];
+  /** The owners of the NFTs to fetch the trading activity from */
+  owners?: string[];
+  /** The marketplaces to fetch the trading activity from */
+  marketplaces?: Marketplace[];
+  /** The tokens to fetch the trading activity from */
+  placedInToken?: string[];
+  /** The price range to fetch the trading activity from */
+  priceRange?: {
+    min: number;
+    max: number;
+  };
+  /** The rank range to fetch the trading activity from */
+  rankRange?: {
+    min: number;
+    max: number;
+  };
+  /** The timestamp range to fetch the trading activity from */
+  timestampRange?: {
+    min: number;
+    max: number;
+  };
+  /** The number of results to return */
+  top?: number;
+  /** The number of results to skip */
+  skip?: number;
+  /** The actions to fetch the trading activity from */
+  actions?: string[];
+  /** The fields to select from the trading activity */
+  select?: SelectFieldsTradingActivity[];
+  /** The fields to order the trading activity by */
+  orderBy?: OrderByTradingActivity[];
+  /** The attributes to fetch the trading activity from */
+  attributes?: MetadataAttribute[];
+}
+
+export const enum OrderByTradingActivity {
+  PriceHighToLow = 'short_price desc',
+  PriceLowToHigh = 'short_price asc',
+  RecentPlaced = 'timestamp desc',
+  OldestPlaced = 'timestamp asc',
+}
+
+export const enum SelectFieldsTradingActivity {
+  'attributes',
+  'collection',
+  'offer_id',
+  'owner',
+  'short_price',
+  'price',
+  'id',
+  'dataType',
+  'marketplace',
+  'payment_token',
+}
+
+export interface TradingActivityResponse {
+  hasMoreResults: boolean;
+  resources: TradingActivity[];
+  getNextPagePayload: TradincActivityArgs;
+  empty: boolean;
+}