@xoxno/sdk-js 0.0.1

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@xoxno/sdk-js",
+  "version": "0.0.1",
+  "description": "The SDK to interact with the XOXNO Protocol!",
+  "main": "./src/index.ts",
+  "scripts": {
+    "test": "jest",
+    "build": "webpack",
+    "lint": "eslint 'src/**/*.ts'",
+    "format": "prettier --write 'src/**/*.ts'",
+    "commit": "git-cz",
+    "release": "semantic-release",
+    "docs": "typedoc --out docs src/**/*.ts"
+  },
+  "config": {
+    "commitizen": {
+      "path": "./node_modules/cz-conventional-changelog"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/XOXNO/sdk-js.git"
+  },
+  "husky": {
+    "hooks": {
+      "commit-msg": "npx --no-install commitlint --edit \"$1\"",
+      "pre-commit": "npm run format && npm run lint && npm run docs",
+      "pre-push": "npm test"
+    }
+  },
+  "keywords": [
+    "XOXNO",
+    "MultiversX",
+    "NFTs",
+    "Blockchain",
+    "Crypto"
+  ],
+  "author": "Mihai Eremia",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/XOXNO/sdk-js/issues"
+  },
+  "homepage": "https://github.com/XOXNO/sdk-js#readme",
+  "devDependencies": {
+    "@commitlint/cli": "^17.5.0",
+    "@commitlint/config-conventional": "^17.4.4",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@types/jest": "^29.5.0",
+    "@types/node": "^18.15.10",
+    "@typescript-eslint/eslint-plugin": "^5.56.0",
+    "@typescript-eslint/parser": "^5.56.0",
+    "commitizen": "^4.3.0",
+    "cz-conventional-changelog": "^3.3.0",
+    "eslint": "^8.36.0",
+    "eslint-config-prettier": "^8.8.0",
+    "eslint-plugin-prettier": "^4.2.1",
+    "husky": "^8.0.3",
+    "jest": "^29.5.0",
+    "prettier": "^2.8.7",
+    "semantic-release": "^21.0.0",
+    "ts-jest": "^29.0.5",
+    "ts-loader": "^9.4.2",
+    "typedoc": "^0.23.28",
+    "typescript": "^5.0.2",
+    "webpack": "^5.76.3",
+    "webpack-cli": "^5.0.1"
+  },
+  "dependencies": {
+    "@multiversx/sdk-core": "^11.5.0",
+    "@multiversx/sdk-network-providers": "^1.3.0",
+    "axios": "^1.3.4"
+  }
+}

package/src/collection/__tests__/collection.test.ts

@@ -0,0 +1,100 @@
+import { CollectionModule } from './../index';
+import { APIClient } from '../../utils/api';
+import { FieldsToSelect } from '../../types';
+
+describe('CollectionModule', () => {
+  let collectionModule: CollectionModule;
+  const inputCollection = 'BANANA-e955fd';
+  beforeAll(() => {
+    APIClient.init('https://api.xoxno.com', '');
+    collectionModule = new CollectionModule();
+  });
+
+  test('getCollectionProfile should return the correct result', async () => {
+    const collectionModule = new CollectionModule();
+    const result = await collectionModule.getCollectionProfile(inputCollection);
+    expect(result.collection).toEqual(inputCollection);
+  });
+
+  it('should get the floor price of a collection', async () => {
+    const floorPrice = await collectionModule.getCollectionFloorPrice(
+      inputCollection
+    );
+    expect(floorPrice).toBeLessThan(1);
+  });
+
+  it('should get the collection attributes', async () => {
+    const attributesInfo = await collectionModule.getCollectionAttributes(
+      inputCollection
+    );
+    expect(attributesInfo).toMatchObject({
+      Accessorie: {
+        Dollars: {
+          attributeOccurrence: 260,
+        },
+      },
+    });
+  });
+
+  it('should get the collection trading activity', async () => {
+    const tradingActivity = await collectionModule.getTradingActivity({
+      collections: [inputCollection],
+      top: 1,
+    });
+    expect(tradingActivity).toMatchObject({
+      getNextPagePayload: {
+        top: 1,
+        skip: 1,
+        collections: [inputCollection],
+      },
+    });
+
+    const tradingActivitySecondPage = await collectionModule.getTradingActivity(
+      tradingActivity.getNextPagePayload
+    );
+    expect(tradingActivitySecondPage).toMatchObject({
+      getNextPagePayload: {
+        top: 1,
+        skip: 2,
+        collections: [inputCollection],
+      },
+    });
+  });
+
+  it('should get fetch and filter NFTs from a collection', async () => {
+    const nfts = await collectionModule.searchNFTs({
+      collection: inputCollection,
+      onlyOnSale: true,
+      top: 1,
+      onlySelectFields: [
+        FieldsToSelect.Attributes,
+        FieldsToSelect.Name,
+        FieldsToSelect.SaleInfo,
+        FieldsToSelect.Rank,
+        FieldsToSelect.Description,
+        FieldsToSelect.Royalties,
+        FieldsToSelect.Collection,
+      ],
+    });
+    expect(nfts).toMatchObject({
+      getNextPagePayload: {
+        top: 1,
+        skip: 1,
+        collection: inputCollection,
+        onlyOnSale: true,
+      },
+    });
+
+    const nftsSecondPage = await collectionModule.searchNFTs(
+      nfts.getNextPagePayload
+    );
+    expect(nftsSecondPage).toMatchObject({
+      getNextPagePayload: {
+        top: 1,
+        skip: 2,
+        collection: inputCollection,
+        onlyOnSale: true,
+      },
+    });
+  });
+});

package/src/collection/index.ts

@@ -0,0 +1,158 @@
+import {
+  ICollectionAttributes,
+  ICollectionProfile,
+  SearchNFTs,
+  SearchNFTsArgs,
+  SearchNFTsResponse,
+} from '../types/collection';
+import { TradincActivityArgs, TradingActivityResponse } from '../types/trading';
+import { APIClient } from '../utils/api';
+import { getActivity } from '../utils/getActivity';
+import { isValidCollectionTicker } from '../utils/regex';
+
+/**
+ * CollectionModule provides a set of methods to interact with NFT collections.
+ * It includes methods for getting collection profile information, floor price,
+ * collection attributes, and searching NFTs within a collection.
+ *
+ * @example
+ * const xoxno = new XOXNO({ apiURL: 'https://api.xoxno.com', apiKey: 'your-api-key' });
+ * const collectionModule = xoxno.collection;
+ */
+export class CollectionModule {
+  private api: APIClient;
+  constructor() {
+    this.api = APIClient.getClient();
+  }
+
+  /**
+   * Fetches the profile of a collection.
+   * @param collection - The ticker of the collection.
+   * @returns A Promise that resolves to the ICollectionProfile object.
+   * @throws An error if the provided collection ticker is invalid.
+   */
+  public getCollectionProfile = async (
+    collection: string
+  ): Promise<ICollectionProfile> => {
+    if (!isValidCollectionTicker(collection)) {
+      throw new Error('Invalid collection ticker: ' + collection);
+    }
+    const response = await this.api.fetchWithTimeout<ICollectionProfile>(
+      `/getCollectionProfile/${collection}`
+    );
+    return response;
+  };
+
+  /**
+   * Fetches the floor price of a collection.
+   * @param collection - The ticker of the collection.
+   * @param token - The token for the floor price calculation (default: 'EGLD').
+   * @returns A Promise that resolves to the collection's floor price as a number.
+   * @throws An error if the provided collection ticker is invalid.
+   */
+  public getCollectionFloorPrice = async (
+    collection: string,
+    token = 'EGLD'
+  ): Promise<number> => {
+    if (!isValidCollectionTicker(collection)) {
+      throw new Error('Invalid collection ticker: ' + collection);
+    }
+    const response = await this.api.fetchWithTimeout<number>(
+      `/getFloorPrice/${collection}/${token}`
+    );
+    return response;
+  };
+
+  /**
+   * Fetches the attributes of a collection.
+   * @param collection - The ticker of the collection.
+   * @returns A Promise that resolves to the ICollectionAttributes object.
+   * @throws An error if the provided collection ticker is invalid.
+   */
+  public getCollectionAttributes = async (
+    collection: string
+  ): Promise<ICollectionAttributes> => {
+    if (!isValidCollectionTicker(collection)) {
+      throw new Error('Invalid collection ticker: ' + collection);
+    }
+    const response = await this.api.fetchWithTimeout<ICollectionAttributes>(
+      `/getCollectionAttributes/${collection}`
+    );
+    return response;
+  };
+
+  /**
+   * Searches for NFTs in a collection based on the provided arguments.
+   * @param args - The SearchNFTsArgs object containing the search parameters.
+   * @returns A Promise that resolves to the SearchNFTsResponse object.
+   * @throws An error if the provided collection ticker is invalid or if the 'top' value is greater than 35.
+   */
+  public searchNFTs = async (
+    args: SearchNFTsArgs
+  ): Promise<SearchNFTsResponse> => {
+    if (!isValidCollectionTicker(args.collection)) {
+      throw new Error('Invalid collection ticker: ' + args.collection);
+    }
+
+    if (args.top && args.top > 35) {
+      throw new Error('Top cannot be greater than 35');
+    }
+
+    const payloadBody: SearchNFTs = {
+      filters: {
+        onSale: args.onlyOnSale || false,
+        marketplace: args.listedOnlyOn || undefined,
+        auctionTypes: args.onlyOnSale
+          ? args.onlyAuctions
+            ? ['NftBid', 'SftAll']
+            : ['Nft', 'SftOnePerPayment']
+          : undefined,
+        tokens: args.listedInToken || undefined,
+        attributes: args.attributes || undefined,
+        range: args.priceRange
+          ? {
+              ...args.priceRange,
+              type: args.onlyAuctions
+                ? 'saleInfoNft/current_bid_short'
+                : 'saleInfoNft/min_bid_short',
+            }
+          : undefined,
+        rankRange: args.rankRange || undefined,
+        levelRange: args.cantinaLevelRange || undefined,
+      },
+      name: args.searchName || '',
+      orderBy: args.orderBy || undefined,
+      collection: args.collection,
+      select: args.onlySelectFields || undefined,
+      top: args.top || 35,
+      skip: args.skip || 0,
+    };
+
+    const buffer = Buffer.from(JSON.stringify(payloadBody)).toString('base64');
+    const response = await this.api.fetchWithTimeout<SearchNFTsResponse>(
+      `/searchNFTs/${buffer}`
+    );
+    return {
+      ...response,
+      getNextPagePayload: {
+        ...args,
+        skip: (args.skip ?? 0) + (args.top ?? 35),
+      },
+      hasMoreResults:
+        response.resultsCount > (args.skip ?? 0) + (args.top ?? 35),
+    };
+  };
+
+  /**
+   * 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/index.ts

@@ -0,0 +1,20 @@
+import { CollectionModule } from './collection';
+import { APIClient } from './utils/api';
+import { API_URL } from './utils/const';
+
+/**
+ * Represents an XOXNO Marketplace SDK, providing a simplified interface for
+ * interacting with an XOXNO API.
+ */
+export class XOXNO {
+  public collection: CollectionModule;
+  /**
+   * Creates a new XOXNO instance.
+   * @param apiUrl - The base URL of the XOXNO API.
+   * @param apiKey - The API key for accessing the XOXNO API.
+   */
+  constructor(apiUrl: string = API_URL, apiKey = '') {
+    APIClient.init(apiUrl, apiKey);
+    this.collection = new CollectionModule();
+  }
+}

package/src/interactions/__tests__/market.test.ts

@@ -0,0 +1,92 @@
+import { SCInteraction } from '../index';
+import { APIClient } from '../../utils/api';
+
+describe('SCInteraction', () => {
+  let sc: SCInteraction;
+  beforeAll(async () => {
+    APIClient.init();
+    sc = await SCInteraction.create();
+  });
+
+  it('should return the XOXNO marketplace cut fees from SC', async () => {
+    const fees = await sc.getMarketplaceFees();
+    expect(fees).toBeDefined();
+    expect(fees).toEqual(100);
+  });
+
+  it('should return the XOXNO marketplace accepted payment tokens', async () => {
+    const tokens = await sc.getAcceptedPaymentTokens();
+    expect(tokens).toBeDefined();
+    expect(tokens).toContain('EGLD');
+  });
+
+  it('should return the XOXNO marketplace global offers unique IDs', async () => {
+    const global_offer_ids = await sc.getGlobalOfferIDs();
+    expect(global_offer_ids).toBeDefined();
+    expect(global_offer_ids.length).toBeGreaterThan(1);
+  });
+
+  it('should return the XOXNO global offer body for an ID', async () => {
+    const global_offer_ids = await sc.getGlobalOfferIDs();
+    expect(global_offer_ids).toBeDefined();
+    expect(global_offer_ids.length).toBeGreaterThan(1);
+    const offer = await sc.getGlobalOfferData(global_offer_ids[0]);
+    expect(offer).toBeDefined();
+    const lastOffer = await sc.getGlobalOfferData(
+      global_offer_ids[global_offer_ids.length - 1]
+    );
+    expect(lastOffer).toBeDefined();
+  });
+
+  it('should return the XOXNO listings count', async () => {
+    const listings = await sc.getListingsCount();
+    expect(listings).toBeDefined();
+    expect(listings).toBeGreaterThan(1);
+  });
+
+  it('should return the XOXNO custom offers count', async () => {
+    const listings = await sc.getOffersCount();
+    expect(listings).toBeDefined();
+    expect(listings).toBeGreaterThan(1);
+  });
+
+  it('should return the XOXNO global offers count', async () => {
+    const listings = await sc.getGlobalOffersCount();
+    expect(listings).toBeDefined();
+    expect(listings).toBeGreaterThan(1);
+  });
+
+  it('should return the XOXNO user deposit balance', async () => {
+    const balance = await sc.getUserPoolBalance(
+      'erd1fmd662htrgt07xxd8me09newa9s0euzvpz3wp0c4pz78f83grt9qm6pn57',
+      'EGLD',
+      0
+    );
+    expect(balance).toBeDefined();
+    expect(balance).toBeGreaterThan(0);
+  });
+
+  it('should return the XOXNO unique listed collections', async () => {
+    const listings = await sc.getCollectionsCount();
+    expect(listings).toBeDefined();
+    expect(listings).toBeGreaterThan(1);
+  });
+
+  it('should return the XOXNO unique auction IDs of a collection', async () => {
+    const IDs = await sc.getAuctionIDsForCollection('COW-cd463d');
+    expect(IDs).toBeDefined();
+    expect(IDs.length).toBeGreaterThan(1);
+  });
+
+  it('should return the XOXNO on sale NFT count of a collection', async () => {
+    const count = await sc.getCollectionNFTsOnSaleCount('COW-cd463d');
+    expect(count).toBeDefined();
+    expect(count).toBeGreaterThan(10);
+  });
+
+  it('should return if the collection is listed on XOXNO', async () => {
+    const isListed = await sc.isCollectionListed('COW-cd463d');
+    expect(isListed).toBeDefined();
+    expect(isListed).toEqual(true);
+  });
+});

package/src/interactions/index.ts

@@ -0,0 +1,228 @@
+import {
+  BigUIntValue,
+  Interaction,
+  SmartContract,
+} from '@multiversx/sdk-core/out';
+import { Address } from '@multiversx/sdk-core/out/address';
+import { GlobalOffer } from '../types/collection';
+import { APIClient } from '../utils/api';
+import { ContractQueryRunner } from '../utils/scCalls';
+import { SmartContractAbis } from '../utils/SmartContractAbis';
+import { getSmartContract } from '../utils/SmartContractService';
+
+export class SCInteraction {
+  private xo: SmartContract;
+  private call: ContractQueryRunner;
+  constructor(marketAbiXOXNO: SmartContract) {
+    this.xo = marketAbiXOXNO;
+    this.call = new ContractQueryRunner();
+  }
+
+  static async create() {
+    const config = APIClient.getClient().config;
+    const marketAbiXOXNO = await SmartContractAbis.getMarket();
+    const xo_abi = getSmartContract(
+      marketAbiXOXNO,
+      new Address(config.XO_SC),
+      'XOXNOProtocol'
+    );
+
+    return new SCInteraction(xo_abi);
+  }
+
+  private async getResult(interaction: Interaction) {
+    return await this.call.runQuery(this.xo, interaction);
+  }
+
+  /**
+   * Gets the percentage of each transaction that will be paid to the marketplace.
+   *
+   * @returns The percentage of each transaction that will be paid to the marketplace.
+   */
+  public getMarketplaceFees = async (): Promise<number> => {
+    const interaction = this.xo.methods.getMarketplaceCutPercentage();
+    const result = await this.getResult(interaction);
+    return parseInt(result.firstValue?.valueOf());
+  };
+
+  /**
+   * Retrieves the list of accepted payment tokens.
+   * @returns {string[]} A list of accepted payment tokens.
+   */
+  public getAcceptedPaymentTokens = async (): Promise<string[]> => {
+    const interaction = this.xo.methods.getAcceptedTokens();
+    const result = await this.getResult(interaction);
+    return result.firstValue?.valueOf();
+  };
+
+  /**
+   * This function returns a list of IDs of global offers.
+   * @returns {number[]} a list of IDs of global offers.
+   */
+
+  public getGlobalOfferIDs = async (): Promise<number[]> => {
+    const interaction = this.xo.methods.getGlobalOffers();
+    const result = await this.getResult(interaction);
+    return result.firstValue?.valueOf().map((id: string) => parseInt(id));
+  };
+
+  /**
+   * Gets the balance of a user in a token of a specific pool.
+   * @param address The address of the user.
+   * @param token The token address.
+   * @param nonce The nonce of the pool.
+   * @returns {number} The balance of the user in the token of the pool.
+   */
+  async getUserPoolBalance(
+    address: string,
+    token: string,
+    nonce: number
+  ): Promise<number> {
+    const result = await this.getResult(
+      this.xo.methods.userDeposit([address, token, nonce])
+    );
+
+    if (!result?.firstValue) {
+      return 0;
+    }
+    return new BigUIntValue(result.firstValue.valueOf().amount)
+      .valueOf()
+      .shiftedBy(-18)
+      .toNumber();
+  }
+
+  // function to determine if the offer is active
+  // based on the offer price and user balance
+  private isOfferActive(offer_price: number, user_balance: number): boolean {
+    return offer_price <= user_balance;
+  }
+
+  /**
+   * Returns the global offer data for the offer with the given id.
+   *
+   * @param global_offer_id The id of the global offer for which to return the data.
+   *
+   * @returns An object containing the global offer data for the offer with the given id. If the global offer id is invalid, the return value will be null.
+   */
+
+  public getGlobalOfferData = async (
+    global_offer_id: number
+  ): Promise<GlobalOffer> => {
+    const interaction = this.xo.methods.getGlobalOffer([global_offer_id]);
+    const result = await this.getResult(interaction);
+    const body = result.firstValue?.valueOf();
+    body.offer_id = parseInt(body.offer_id.valueOf());
+    body.marketplace = 'XO';
+    body.short_price = parseFloat(
+      new BigUIntValue(body.price).valueOf().shiftedBy(-18).toString()
+    );
+    body.new_version = Boolean(body.new_version);
+    if (!body.new_version) {
+      body.isActive = this.isOfferActive(
+        body.short_price,
+        await this.getUserPoolBalance(
+          body.owner,
+          body.payment_token,
+          body.payment_nonce
+        )
+      );
+    } else {
+      body.isActive = true;
+    }
+    body.quantity = parseInt(body.quantity.valueOf());
+    body.payment_nonce = parseInt(body.payment_nonce.valueOf());
+    body.price = body.price.valueOf();
+
+    body.timestamp = parseInt(body.timestamp.valueOf());
+    body.owner = body.owner.valueOf().toString();
+    if (body.attributes) {
+      body.attributes = JSON.parse(
+        Buffer.from(body.attributes.valueOf().toString(), 'base64').toString(
+          'ascii'
+        )
+      );
+    }
+    return body as GlobalOffer;
+  };
+
+  /** Gets the number of listings.
+   * @returns {number} The number of listings.
+   * */
+  public async getListingsCount(): Promise<number> {
+    const result = await this.getResult(this.xo.methods.getListingsCount());
+    const count = parseInt(result.firstValue?.valueOf());
+    return count;
+  }
+
+  /** Gets the number of custom offers.
+   * @returns {number} The number of custom offers.
+   * */
+  public async getOffersCount(): Promise<number> {
+    const result = await this.getResult(this.xo.methods.getOffersCount());
+    const count = parseInt(result.firstValue?.valueOf());
+    return count;
+  }
+
+  /** Gets the number of global offers.
+   * @returns {number} The number of global offers.
+   * */
+  public async getGlobalOffersCount(): Promise<number> {
+    const result = await this.getResult(this.xo.methods.getGlobalOffersCount());
+    const count = parseInt(result.firstValue?.valueOf());
+    return count;
+  }
+
+  /** Gets the number of collections listed.
+   * @returns {number} The number of collections listed.
+   * */
+  public async getCollectionsCount(): Promise<number> {
+    const result = await this.getResult(this.xo.methods.getCollectionsCount());
+    const count = parseInt(result.firstValue?.valueOf());
+    return count;
+  }
+
+  /**
+   * Checks whether a collection is listed with at least 1 NFT.
+   *
+   * @param collection name of the collection
+   * @return true if the collection is listed, false otherwise
+   */
+  public async isCollectionListed(collection: string): Promise<boolean> {
+    const result = await this.getResult(
+      this.xo.methods.isCollectionListed([collection])
+    );
+    return Boolean(result.firstValue?.valueOf());
+  }
+
+  /** Gets the on sale NFT count of the collection.
+   *
+   * @param collection The collection identifier for which one wants to get the on sale NFT count.
+   *
+   * @returns {number} The on sale NFT count of the collection.
+   * */
+  public async getCollectionNFTsOnSaleCount(
+    collection: string
+  ): Promise<number> {
+    const result = await this.getResult(
+      this.xo.methods.getTokenItemsForSaleCount([collection])
+    );
+    return parseInt(result.firstValue?.valueOf());
+  }
+
+  /** Gets the active unique auction IDs of collection.
+   *
+   * @param collection The collection identifier for which one wants to get the active unique auction IDs.
+   *
+   * @returns {number[]} The active unique auction IDs of collection.
+   * */
+
+  public async getAuctionIDsForCollection(
+    collection: string
+  ): Promise<number[]> {
+    const result = await this.getResult(
+      this.xo.methods.getAuctionsForTicker([collection])
+    );
+    const ids = result.firstValue?.valueOf().map((id: string) => parseInt(id));
+    return ids;
+  }
+}