feat: add support for polygon wearables in explorer and marketplace APIs (#445)

* feat: add support for polygon wearables in explorer and marketplace APIs

- Updated ItemType to include 'polygonWearables'.
- Enhanced marketplace API fetcher to handle 'polygonWearables' item type, allowing for fetching both wearable_v2 and smart_wearable_v1.
- Modified explorer handler to support isPolygonWearable filter, including amount in responses when requested.
- Added tests to validate new functionality for polygon wearables and ensure correct behavior with existing filters.

* feat: add explorer emotes handler and route

- Introduced a new handler for fetching emotes in the explorer, supporting pagination and filtering.
- Added a route to the router for accessing emotes by address.
- Implemented tests to validate the functionality of the new emotes endpoint, including error handling and response structure.
- Enhanced existing data generation utilities to support emote entities.

* refactor: streamline itemType and network handling in fetchers and handlers

- Removed 'polygonWearables' from ItemType and updated related logic to handle network-specific wearables.
- Enhanced marketplace API fetcher to support network parameter for fetching wearables based on the selected network (Ethereum or Polygon).
- Updated explorer handler to utilize network parameter instead of isPolygonWearable, simplifying the filters and response structure.
- Refactored tests to validate new network-based filtering and ensure correct behavior across different scenarios.

* refactor: update network handling to use enum values across fetchers and handlers

- Replaced string literals for network parameters with the Network enum in elements-fetcher, marketplace-api-fetcher, explorer-handler, and related logic.
- Adjusted tests to validate the new enum-based network handling, ensuring consistency and correctness in API responses.
- Enhanced type safety and clarity in network-related code throughout the application.

* refactor: validate network parameter in explorer handler and update tests

- Enhanced the explorer handler to validate the network parameter, ensuring only valid Network enum values (ETHEREUM or MATIC) are accepted.
- Updated integration tests to reflect changes in network handling, replacing instances of 'polygon' with 'MATIC' and ensuring consistency in test descriptions and expectations.

Author: AndresMorelos

src/adapters/elements-fetcher.ts

@@ -1,3 +1,4 @@
+import { Network } from '@dcl/schemas'
 import { AppComponents } from '../types'
 import { IBaseComponent } from '@well-known-components/interfaces'
 import { createLowerCaseKeysCache } from './lowercase-keys-cache'
@@ -50,6 +51,7 @@ export type ElementsFilters = {
   orderBy?: string
   direction?: string
   itemType?: ItemType
+  network?: Network
 }
 
 export type LegacyElementsFetcher<T> = IBaseComponent & {

src/adapters/marketplace-api-fetcher.ts

@@ -1,5 +1,5 @@
 import { IBaseComponent } from '@well-known-components/interfaces'
-import { WearableCategory, EmoteCategory } from '@dcl/schemas'
+import { WearableCategory, EmoteCategory, Network } from '@dcl/schemas'
 import { OnChainWearable, OnChainEmote, Name, AppComponents } from '../types'
 import { ItemType } from './elements-fetcher'
 
@@ -84,6 +84,8 @@ export type MarketplaceApiParams = {
 
   // Item type
   itemType?: ItemType
+  // Network
+  network?: Network
 }
 
 /**
@@ -235,8 +237,22 @@ export async function createMarketplaceApiFetcher(
     if (params.direction) {
       queryParams.set('direction', params.direction)
     }
-    if (params.itemType && params.itemType === 'smartWearable') {
-      queryParams.set('itemType', 'smart_wearable_v1')
+
+    // Handle itemType and network parameters
+    if (params.itemType) {
+      if (params.itemType === 'smartWearable') {
+        queryParams.append('itemType', 'smart_wearable_v1')
+      } else if (params.itemType === 'wearable') {
+        // Handle network-specific wearable types
+        if (params.network === Network.MATIC) {
+          // Polygon: wearable_v2 and smart_wearable_v1
+          queryParams.append('itemType', 'wearable_v2')
+          queryParams.append('itemType', 'smart_wearable_v1')
+        } else if (params.network === Network.ETHEREUM) {
+          // Ethereum: only wearable_v1
+          queryParams.append('itemType', 'wearable_v1')
+        }
+      }
     }
 
     const queryString = queryParams.toString()

src/controllers/handlers/explorer-emotes-handler.ts

@@ -0,0 +1,122 @@
+import { Entity } from '@dcl/schemas'
+import { fetchAndPaginate, paginationObject } from '../../logic/pagination'
+import { createCombinedSorting } from '../../logic/sorting'
+import {
+  AppComponents,
+  HandlerContextWithPath,
+  InvalidRequestError,
+  OnChainEmote,
+  PaginatedResponse
+} from '../../types'
+import { createFilters } from './items-commons'
+
+export const ON_CHAIN = 'on-chain'
+
+const VALID_COLLECTION_TYPES = ['on-chain']
+
+export type MixedOnChainEmote = OnChainEmote & {
+  type: typeof ON_CHAIN
+  entity: Entity
+}
+
+export type MixedEmote = MixedOnChainEmote
+
+export type MixedEmoteResponse = Omit<MixedEmote, 'minTransferredAt' | 'maxTransferredAt'>
+
+export type MixedEmoteTrimmedResponse = {
+  entity: Entity
+  amount?: number
+}
+
+async function fetchCombinedElements(
+  components: Pick<AppComponents, 'emotesFetcher' | 'entitiesFetcher'>,
+  collectionTypes: string[],
+  address: string
+): Promise<MixedEmote[]> {
+  async function fetchOnChainEmotes(): Promise<MixedOnChainEmote[]> {
+    const { elements } = await components.emotesFetcher.fetchOwnedElements(address)
+    if (!elements.length) {
+      return []
+    }
+
+    const urns = elements.map((e) => e.urn)
+    const entities = await components.entitiesFetcher.fetchEntities(urns)
+
+    return elements.reduce<MixedOnChainEmote[]>((acc, emote, i) => {
+      const entity = entities[i]
+      if (entity) {
+        acc.push({
+          type: ON_CHAIN,
+          ...emote,
+          entity
+        })
+      }
+      return acc
+    }, [])
+  }
+
+  const emotes = collectionTypes.includes(ON_CHAIN) ? await fetchOnChainEmotes() : []
+
+  return emotes
+}
+
+export async function explorerEmotesHandler(
+  context: HandlerContextWithPath<'emotesFetcher' | 'entitiesFetcher', '/explorer/:address/emotes'>
+): Promise<PaginatedResponse<MixedEmoteResponse> | PaginatedResponse<MixedEmoteTrimmedResponse>> {
+  const { address } = context.params
+  const pagination = paginationObject(context.url)
+  const filter = createFilters(context.url)
+  const sorting = createCombinedSorting(context.url)
+  const collectionTypes = context.url.searchParams.has('collectionType')
+    ? context.url.searchParams.getAll('collectionType')
+    : VALID_COLLECTION_TYPES
+  const trimmedParam = context.url.searchParams.get('trimmed')
+  const isTrimmed = trimmedParam === 'true' || trimmedParam === '1'
+  const includeAmountParam = context.url.searchParams.get('includeAmount')
+  const includeAmount = includeAmountParam === 'true' || includeAmountParam === '1'
+
+  if (collectionTypes.some((type) => !VALID_COLLECTION_TYPES.includes(type))) {
+    throw new InvalidRequestError(`Invalid collection type. Valid types are: ${VALID_COLLECTION_TYPES.join(', ')}.`)
+  }
+
+  const page = await fetchAndPaginate<MixedEmote>(
+    () => fetchCombinedElements(context.components, collectionTypes, address),
+    pagination,
+    filter,
+    sorting
+  )
+
+  if (isTrimmed) {
+    const results: MixedEmoteTrimmedResponse[] = page.elements.map((emote) => {
+      const result: MixedEmoteTrimmedResponse = {
+        entity: emote.entity
+      }
+      if (includeAmount) {
+        result.amount = emote.individualData?.length || 0
+      }
+      return result
+    })
+
+    return {
+      status: 200,
+      body: {
+        ...page,
+        elements: results
+      }
+    }
+  } else {
+    const results: MixedEmoteResponse[] = []
+    for (const emote of page.elements) {
+      const { minTransferredAt, maxTransferredAt, ...clean } = emote
+      results.push({ ...clean })
+    }
+
+    return {
+      status: 200,
+      body: {
+        ...page,
+        elements: results
+      }
+    }
+  }
+}

src/controllers/handlers/explorer-handler.ts

@@ -1,4 +1,4 @@
-import { Entity } from '@dcl/schemas'
+import { Entity, Network } from '@dcl/schemas'
 import { fetchThirdPartyWearablesFromThirdPartyName } from '../../logic/fetch-elements/fetch-third-party-wearables'
 import { fetchAndPaginate, paginationObject } from '../../logic/pagination'
 import { createCombinedSorting } from '../../logic/sorting'
@@ -41,10 +41,12 @@ export type MixedWearableResponse = Omit<MixedWearable, 'minTransferredAt' | 'ma
 
 export type MixedWearableTrimmedResponse = {
   entity: ExplorerWearableEntity
+  amount?: number
 }
 
 export type WearableFilters = {
   isSmartWearable: boolean
+  network?: Network
 }
 
 async function fetchCombinedElements(
@@ -85,9 +87,17 @@ async function fetchCombinedElements(
   }
 
   async function fetchOnChainWearables(): Promise<MixedOnChainWearable[]> {
+    let itemType: 'wearable' | 'smartWearable' = 'wearable'
+
+    if (filters.isSmartWearable) {
+      itemType = 'smartWearable'
+    }
+
     const { elements } = await components.wearablesFetcher.fetchOwnedElements(address, undefined, {
-      itemType: filters.isSmartWearable ? 'smartWearable' : 'wearable'
+      itemType,
+      network: filters.network
     })
+
     if (!elements.length) {
       return []
     }
@@ -148,9 +158,13 @@ async function fetchCombinedElements(
   }
 
   const [baseItems, nftItems, thirdPartyItems] = await Promise.all([
-    filters.isSmartWearable ? [] : collectionTypes.includes(BASE_WEARABLE) ? fetchBaseWearables() : [],
+    filters.isSmartWearable || filters.network
+      ? []
+      : collectionTypes.includes(BASE_WEARABLE)
+        ? fetchBaseWearables()
+        : [],
     collectionTypes.includes(ON_CHAIN) ? fetchOnChainWearables() : [],
-    filters.isSmartWearable
+    filters.isSmartWearable || filters.network
       ? []
       : collectionTypes.includes(THIRD_PARTY)
         ? fetchThirdPartyWearables(thirdPartyCollectionId)
@@ -185,23 +199,37 @@ export async function explorerHandler(
   const isTrimmed = trimmedParam === 'true' || trimmedParam === '1'
   const isSmartWearableParam = context.url.searchParams.get('isSmartWearable')
   const isSmartWearable = isSmartWearableParam === 'true' || isSmartWearableParam === '1'
+  const networkParam = context.url.searchParams.get('network')
+  // Validate network parameter - only allow valid Network enum values (ETHEREUM or MATIC)
+  const network = networkParam === Network.ETHEREUM || networkParam === Network.MATIC ? networkParam : undefined
+  const includeAmountParam = context.url.searchParams.get('includeAmount')
+  const includeAmount = includeAmountParam === 'true' || includeAmountParam === '1'
 
   if (collectionTypes.some((type) => !VALID_COLLECTION_TYPES.includes(type))) {
     throw new InvalidRequestError(`Invalid collection type. Valid types are: ${VALID_COLLECTION_TYPES.join(', ')}.`)
   }
 
   const page = await fetchAndPaginate<MixedWearable>(
     () =>
-      fetchCombinedElements(context.components, collectionTypes, thirdPartyCollectionIds, address, { isSmartWearable }),
+      fetchCombinedElements(context.components, collectionTypes, thirdPartyCollectionIds, address, {
+        isSmartWearable,
+        network
+      }),
     pagination,
     filter,
     sorting
   )
 
   if (isTrimmed) {
-    const results: MixedWearableTrimmedResponse[] = page.elements.map((wearable) => ({
-      entity: buildTrimmedEntity(wearable.entity)
-    }))
+    const results: MixedWearableTrimmedResponse[] = page.elements.map((wearable) => {
+      const result: MixedWearableTrimmedResponse = {
+        entity: buildTrimmedEntity(wearable.entity)
+      }
+      if (includeAmount) {
+        result.amount = wearable.individualData?.length || 0
+      }
+      return result
+    })
 
     return {
       status: 200,

src/controllers/routes.ts

@@ -13,6 +13,7 @@ import {
 } from './handlers/third-party-wearables-handler'
 import { wearablesHandler } from './handlers/wearables-handler'
 import { explorerHandler } from './handlers/explorer-handler'
+import { explorerEmotesHandler } from './handlers/explorer-emotes-handler'
 import { errorHandler } from './handlers/errorHandler'
 import { aboutHandler } from './handlers/about-handler'
 import { outfitsHandler } from './handlers/outfits-handler'
@@ -49,6 +50,7 @@ export async function setupRouter(_: GlobalContext): Promise<Router<GlobalContex
   router.get('/contracts/pois', getPOIsHandler)
   router.get('/contracts/denylisted-names', getNameDenylistHandler)
   router.get('/explorer/:address/wearables', explorerHandler)
+  router.get('/explorer/:address/emotes', explorerEmotesHandler)
   router.get('/parcels/:x/:y/operators', parcelOperatorsHandler)
 
   return router

src/logic/fetch-elements/fetch-items.ts

@@ -1,4 +1,4 @@
-import { EmoteCategory, WearableCategory } from '@dcl/schemas'
+import { EmoteCategory, WearableCategory, Network } from '@dcl/schemas'
 import { Item, OnChainEmote, OnChainWearable, Pagination } from '../../types'
 import { MarketplaceApiParams } from '../../adapters/marketplace-api-fetcher'
 import { ElementsFilters, ElementsFetcherDependencies, ItemType } from '../../adapters/elements-fetcher'
@@ -43,6 +43,11 @@ export function buildMarketplaceApiParams(
     params.itemType = filters.itemType
   }
 
+  // Network
+  if (filters?.network) {
+    params.network = filters.network
+  }
+
   return params
 }
 
@@ -190,23 +195,34 @@ export async function fetchWearables(
     },
     async () => {
       // TheGraph fallback implementation
-      const wearableQueryBuilder = createItemQueryBuilder((filters?.itemType || 'wearable') as ItemType)
+      const itemType = (filters?.itemType || 'wearable') as ItemType
+      const network = filters?.network
+
+      // Determine which subgraphs to query based on network filter
+      const shouldQueryEthereum = !network || network === Network.ETHEREUM
+      const shouldQueryMatic = !network || network === Network.MATIC
+
+      const wearableQueryBuilder = createItemQueryBuilder(itemType, network)
 
       const [ethereumResult, maticResult] = await Promise.all([
-        fetchNFTsPaginated<WearableFromQuery>(
-          theGraph.ethereumCollectionsSubgraph,
-          wearableQueryBuilder,
-          owner,
-          pagination,
-          filters
-        ),
-        fetchNFTsPaginated<WearableFromQuery>(
-          theGraph.maticCollectionsSubgraph,
-          wearableQueryBuilder,
-          owner,
-          pagination,
-          filters
-        )
+        shouldQueryEthereum
+          ? fetchNFTsPaginated<WearableFromQuery>(
+              theGraph.ethereumCollectionsSubgraph,
+              wearableQueryBuilder,
+              owner,
+              pagination,
+              filters
+            )
+          : Promise.resolve({ elements: [], totalAmount: 0 }),
+        shouldQueryMatic
+          ? fetchNFTsPaginated<WearableFromQuery>(
+              theGraph.maticCollectionsSubgraph,
+              wearableQueryBuilder,
+              owner,
+              pagination,
+              filters
+            )
+          : Promise.resolve({ elements: [], totalAmount: 0 })
       ])
 
       const allWearables = [...ethereumResult.elements, ...maticResult.elements]

src/logic/fetch-elements/graph-pagination.ts

@@ -1,4 +1,5 @@
 import { ISubgraphComponent } from '@well-known-components/thegraph-component'
+import { Network } from '@dcl/schemas'
 import { ElementsFilters, ItemType } from '../../adapters/elements-fetcher'
 
 interface NFT {
@@ -188,15 +189,24 @@ async function fetchAllNFTsUpTo<E extends NFT>(
 /**
  * Creates a query builder for items (wearables/emotes)
  */
-export function createItemQueryBuilder(category: ItemType) {
+export function createItemQueryBuilder(category: ItemType, network?: Network) {
   let itemTypeFilter: string
 
   if (category === 'smartWearable') {
     itemTypeFilter = `itemType: smart_wearable_v1`
   } else if (category === 'emote') {
     itemTypeFilter = `itemType: emote_v1`
   } else if (category === 'wearable') {
-    itemTypeFilter = `itemType_in: [wearable_v1, wearable_v2, smart_wearable_v1]`
+    if (network === Network.MATIC) {
+      // Polygon wearables: only wearable_v2 and smart_wearable_v1
+      itemTypeFilter = `itemType_in: [wearable_v2, smart_wearable_v1]`
+    } else if (network === Network.ETHEREUM) {
+      // Ethereum wearables: only wearable_v1
+      itemTypeFilter = `itemType: wearable_v1`
+    } else {
+      // No network filter: all wearable types
+      itemTypeFilter = `itemType_in: [wearable_v1, wearable_v2, smart_wearable_v1]`
+    }
   }
 
   return (filters: string, orderBy: string, orderDirection: string, first: number) => `