@faststore/api 1.8.2 → 1.8.5

package/src/platforms/vtex/resolvers/offer.ts

@@ -1,13 +1,13 @@
-import type { Resolver } from '..'
-import type { StoreAggregateOffer } from './aggregateOffer'
 import {
-  getFirstSeller,
+  availability,
   inStock,
   inStockOrderFormItem,
-  getItemPriceByKey,
+  price,
+  sellingPrice,
 } from '../utils/productStock'
+import type { Resolver } from '..'
+import type { StoreAggregateOffer } from './aggregateOffer'
 import type { ArrayElementType } from '../../../typings'
-import type { Item } from '../clients/search/types/ProductSearchResult'
 import type { EnhancedSku } from '../utils/enhanceSku'
 import type { OrderFormItem } from '../clients/commerce/types/OrderForm'
 
@@ -17,98 +17,93 @@ type SearchProduct = ArrayElementType<
 >
 type Root = SearchProduct | OrderFormProduct
 
-const isSearchItem = (item: any): item is Item => 'sellers' in item
-const isOrderFormItem = (item: any): item is OrderFormProduct =>
-  'skuName' in item
+const isSearchItem = (item: Root): item is SearchProduct =>
+  'Price' in item && 'seller' in item && 'product' in item
 
-const getAvailability = (available: boolean) =>
-  available ? 'https://schema.org/InStock' : 'https://schema.org/OutOfStock'
+const isOrderFormItem = (item: Root): item is OrderFormProduct =>
+  'skuName' in item
 
 export const StoreOffer: Record<string, Resolver<Root>> = {
   priceCurrency: () => '',
-  priceValidUntil: (item) => {
-    if (isSearchItem(item)) {
-      return getFirstSeller(item.sellers)?.commertialOffer.PriceValidUntil ?? ''
+  priceValidUntil: (root) => {
+    if (isSearchItem(root)) {
+      return root.PriceValidUntil ?? ''
     }
 
-    if (isOrderFormItem(item)) {
-      return item.priceValidUntil ?? ''
+    if (isOrderFormItem(root)) {
+      return root.priceValidUntil ?? ''
     }
 
     return null
   },
   itemCondition: () => 'https://schema.org/NewCondition',
-  availability: async (item) => {
-    if (isSearchItem(item)) {
-      return getAvailability(!!inStock(item))
+  availability: async (root) => {
+    if (isSearchItem(root)) {
+      return availability(inStock(root))
     }
 
-    if (isOrderFormItem(item)) {
-      return getAvailability(inStockOrderFormItem(item.availability))
+    if (isOrderFormItem(root)) {
+      return availability(inStockOrderFormItem(root.availability))
     }
 
     return null
   },
-  seller: (item) => {
-    if (isSearchItem(item)) {
+  seller: (root) => {
+    if (isSearchItem(root)) {
       return {
-        identifier: getFirstSeller(item.sellers)?.sellerId ?? '',
+        identifier: root.seller.sellerId ?? '',
       }
     }
 
-    if (isOrderFormItem(item)) {
+    if (isOrderFormItem(root)) {
       return {
-        identifier: item.seller,
+        identifier: root.seller,
       }
     }
 
     return null
   },
-  price: (item) => {
-    if (isSearchItem(item)) {
-      return getItemPriceByKey(item, 'spotPrice')
+  price: (root) => {
+    if (isSearchItem(root)) {
+      return price(root)
     }
 
-    if (isOrderFormItem(item)) {
-      return item.price / 1e2
+    if (isOrderFormItem(root)) {
+      return root.price / 1e2
     }
 
     return null
   },
-  sellingPrice: (item) => {
-    if (isSearchItem(item)) {
-      return getItemPriceByKey(item, 'Price')
+  sellingPrice: (root) => {
+    if (isSearchItem(root)) {
+      return sellingPrice(root)
     }
 
-    if (isOrderFormItem(item)) {
-      return item.sellingPrice / 1e2
+    if (isOrderFormItem(root)) {
+      return root.sellingPrice / 1e2
     }
 
     return null
   },
-  listPrice: (item) => {
-    if (isSearchItem(item)) {
-      return getItemPriceByKey(item, 'ListPrice')
+  listPrice: (root) => {
+    if (isSearchItem(root)) {
+      return root.ListPrice
     }
 
-    if (isOrderFormItem(item)) {
-      return item.listPrice / 1e2
+    if (isOrderFormItem(root)) {
+      return root.listPrice / 1e2
     }
 
     return null
   },
   itemOffered: ({ product }) => product,
-  quantity: (item) => {
-    if (isSearchItem(item)) {
-      return item.sellers.reduce(
-        (quantity, seller) =>
-          quantity + seller.commertialOffer.AvailableQuantity,
-        0
-      )
+  quantity: (root) => {
+    if (isSearchItem(root)) {
+      return root.AvailableQuantity ?? 0
     }
 
-    if (isOrderFormItem(item)) {
-      return item.quantity
+    if (isOrderFormItem(root)) {
+      return root.quantity
     }
 
     return null

package/src/platforms/vtex/resolvers/product.ts

@@ -1,9 +1,9 @@
+import { enhanceCommercialOffer } from '../utils/enhanceCommercialOffer'
+import { bestOfferFirst } from '../utils/productStock'
+import type { EnhancedCommercialOffer } from '../utils/enhanceCommercialOffer'
 import type { Resolver } from '..'
-import { sortOfferByPrice } from '../utils/productStock'
 import type { PromiseType } from '../../../typings'
 import type { Query } from './query'
-import type { Item } from '../clients/search/types/ProductSearchResult'
-import type { EnhancedSku } from '../utils/enhanceSku'
 
 type Root = PromiseType<ReturnType<typeof Query.product>>
 
@@ -19,7 +19,7 @@ const nonEmptyArray = <T>(array: T[] | null | undefined) =>
   Array.isArray(array) && array.length > 0 ? array : null
 
 export const StoreProduct: Record<string, Resolver<Root>> & {
-  offers: Resolver<Root, any, { items: Item[]; product: EnhancedSku }>
+  offers: Resolver<Root, any, EnhancedCommercialOffer[]>
   isVariantOf: Resolver<Root, any, Root>
 } = {
   productID: ({ itemId }) => itemId,
@@ -66,12 +66,16 @@ export const StoreProduct: Record<string, Resolver<Root>> & {
   gtin: ({ referenceId }) => referenceId[0]?.Value ?? '',
   review: () => [],
   aggregateRating: () => ({}),
-  offers: (product): { items: Item[]; product: Root } => {
-    return {
-      items: sortOfferByPrice(product.isVariantOf.items),
-      product,
-    }
-  },
+  offers: (root) =>
+    root.sellers
+      .flatMap((seller) =>
+        enhanceCommercialOffer({
+          offer: seller.commertialOffer,
+          seller,
+          product: root,
+        })
+      )
+      .sort(bestOfferFirst),
   isVariantOf: (root) => root,
   additionalProperty: ({ variations = [] }) => {
     return variations.flatMap(({ name, values }) =>

package/src/platforms/vtex/utils/enhanceCommercialOffer.ts

@@ -0,0 +1,24 @@
+import type {
+  CommertialOffer,
+  Seller,
+} from '../clients/search/types/ProductSearchResult'
+import type { EnhancedSku } from './enhanceSku'
+
+export type EnhancedCommercialOffer = CommertialOffer & {
+  seller: Seller
+  product: EnhancedSku
+}
+
+export const enhanceCommercialOffer = ({
+  offer,
+  seller,
+  product,
+}: {
+  offer: CommertialOffer
+  seller: Seller
+  product: EnhancedSku
+}): EnhancedCommercialOffer => ({
+  ...offer,
+  product,
+  seller,
+})

package/src/platforms/vtex/utils/productStock.ts

@@ -1,33 +1,30 @@
-import type {
-  Item,
-  Seller,
-  CommertialOffer,
-} from '../clients/search/types/ProductSearchResult'
+import type { CommertialOffer } from '../clients/search/types/ProductSearchResult'
 
-export const inStock = (item: Item) =>
-  item.sellers.find((seller) => seller.commertialOffer.AvailableQuantity > 0)
+export const inStock = (offer: Pick<CommertialOffer, 'AvailableQuantity'>) =>
+  offer.AvailableQuantity > 0
 
-export const getFirstSeller = (sellers: Seller[]): Seller | undefined =>
-  sellers[0]
+export const price = (offer: Pick<CommertialOffer, 'spotPrice'>) =>
+  offer.spotPrice ?? 0
+export const sellingPrice = (offer: CommertialOffer) => offer.Price ?? 0
 
-export const getItemPriceByKey = (
-  item: Item,
-  key: keyof CommertialOffer
-): number => getFirstSeller(item.sellers)?.commertialOffer[key] ?? 0
+export const availability = (available: boolean) =>
+  available ? 'https://schema.org/InStock' : 'https://schema.org/OutOfStock'
 
 // Smallest Available Selling Price First
-export const sortOfferByPrice = (items: Item[]): Item[] =>
-  items.sort((a, b) => {
-    if (inStock(a) && !inStock(b)) {
-      return -1
-    }
+export const bestOfferFirst = (
+  a: Pick<CommertialOffer, 'AvailableQuantity' | 'spotPrice'>,
+  b: Pick<CommertialOffer, 'AvailableQuantity' | 'spotPrice'>
+) => {
+  if (inStock(a) && !inStock(b)) {
+    return -1
+  }
 
-    if (!inStock(a) && inStock(b)) {
-      return 1
-    }
+  if (!inStock(a) && inStock(b)) {
+    return 1
+  }
 
-    return getItemPriceByKey(a, 'Price') - getItemPriceByKey(b, 'Price')
-  })
+  return price(a) - price(b)
+}
 
-export const inStockOrderFormItem = (availability: string) =>
-  availability === 'available'
+export const inStockOrderFormItem = (itemAvailability: string) =>
+  itemAvailability === 'available'

package/src/typeDefs/aggregateOffer.graphql

@@ -1,10 +1,25 @@
+"""
+Aggregate offer information, for a given SKU that is available to be fulfilled by multiple sellers.
+"""
 type StoreAggregateOffer {
-  # Highest spot price amongst all sellers
+  """
+  Highest price among all sellers.
+  """
   highPrice: Float!
-  # Lowest spot price amongst all sellers
+  """
+  Lowest price among all sellers.
+  """
   lowPrice: Float!
-  # Number of sellers selling this sku
+  """
+  Number of sellers selling this SKU.
+  """
   offerCount: Int!
+  """
+  ISO code of the currency used for the offer prices.
+  """
   priceCurrency: String!
+  """
+  Array with information on each available offer.
+  """
   offers: [StoreOffer!]!
 }

package/src/typeDefs/aggregateRating.graphql

@@ -1,4 +1,13 @@
+"""
+Average rating, based on multiple ratings or reviews.
+"""
 type StoreAggregateRating {
+  """
+  Value of the aggregate rating.
+  """
   ratingValue: Float!
+  """
+  Total number of ratings.
+  """
   reviewCount: Int!
 }

package/src/typeDefs/author.graphql

@@ -1,3 +1,9 @@
+"""
+information about the author of a product review or rating.
+"""
 type StoreAuthor {
+  """
+  Author name.
+  """
   name: String!
 }

package/src/typeDefs/brand.graphql

@@ -1,3 +1,9 @@
+"""
+Brand of a given product.
+"""
 type StoreBrand {
+  """
+  Brand name.
+  """
   name: String!
 }

package/src/typeDefs/breadcrumb.graphql

@@ -1,10 +1,31 @@
+"""
+Item of a list.
+"""
 type StoreListItem {
+  """
+  List item value.
+  """
   item: String!
+  """
+  Name of the list item.
+  """
   name: String!
+  """
+  Position of the item in the list.
+  """
   position: Int!
 }
 
+"""
+List of items consisting of chain linked web pages, ending with the current page.
+"""
 type StoreBreadcrumbList {
+  """
+  Array with breadcrumb elements.
+  """
   itemListElement: [StoreListItem!]!
+  """
+  Number of breadcrumbs in the list.
+  """
   numberOfItems: Int!
 }

package/src/typeDefs/cart.graphql

@@ -1,13 +1,37 @@
+"""
+Shopping cart message.
+"""
 type StoreCartMessage {
+  """
+  Shopping cart message text.
+  """
   text: String!
+  """
+  Shopping cart message status, which can be `INFO`, `WARNING` OR `ERROR`.
+  """
   status: StoreStatus!
 }
 
+"""
+Shopping cart information.
+"""
 type StoreCart {
+  """
+  Order information, including `orderNumber` and `acceptedOffer`.
+  """
   order: StoreOrder!
+  """
+  List of shopping cart messages.
+  """
   messages: [StoreCartMessage!]!
 }
 
+"""
+Shopping cart identification input.
+"""
 input IStoreCart {
+  """
+  Order information, including `orderNumber` and `acceptedOffer`.
+  """
   order: IStoreOrder!
 }

package/src/typeDefs/collection.graphql

@@ -1,3 +1,6 @@
+"""
+Product collection type. Possible values are `Department`, `Category`, `Brand` or `Cluster`.
+"""
 enum StoreCollectionType {
   Department
   Category
@@ -5,22 +8,56 @@ enum StoreCollectionType {
   Cluster
 }
 
+"""
+Product collection facet, used for search.
+"""
 type StoreCollectionFacet {
+  """
+  Facet key.
+  """
   key: String!
+  """
+  Facet value.
+  """
   value: String!
 }
 
+"""
+Collection meta information. Used for search.
+"""
 type StoreCollectionMeta {
+  """
+  List of selected collection facets.
+  """
   selectedFacets: [StoreCollectionFacet!]!
 }
 
+"""
+Product collection information.
+"""
 type StoreCollection {
-  # Meta tag data
+  """
+  Meta tag data.
+  """
   seo: StoreSeo!
-  # location for structured data
+  """
+  List of items consisting of chain linked web pages, ending with the current page.
+  """
   breadcrumbList: StoreBreadcrumbList!
+  """
+  Collection meta information. Used for search.
+  """
   meta: StoreCollectionMeta!
+  """
+  Collection ID.
+  """
   id: ID!
+  """
+  Corresponding collection URL slug, with which to retrieve this entity.
+  """
   slug: String!
+  """
+  Collection type.
+  """
   type: StoreCollectionType!
 }

package/src/typeDefs/facet.graphql

@@ -1,14 +1,43 @@
+"""
+Search facet information.
+"""
 type StoreFacet {
+  """
+  Facet key.
+  """
   key: String!
+  """
+  Facet label.
+  """
   label: String!
+  """
+  Array with information on each facet value.
+  """
   values: [StoreFacetValue!]!
+  """
+  Facet type. Possible values are `BOOLEAN` and `RANGE`.
+  """
   type: StoreFacetType!
 }
 
+"""
+Information of a specific facet value.
+"""
 type StoreFacetValue {
+  """
+  Facet value.
+  """
   value: String!
+  """
+  Facet value label.
+  """
   label: String!
+  """
+  Indicates whether facet is selected.
+  """
   selected: Boolean!
-  # Number of items with this facet
+  """
+  Number of items with this facet.
+  """
   quantity: Int!
 }

package/src/typeDefs/image.graphql

@@ -1,9 +1,27 @@
+"""
+Image.
+"""
 type StoreImage {
+  """
+  Image URL.
+  """
   url: String!
+  """
+  Alias for the image.
+  """
   alternateName: String!
 }
 
+"""
+Image input.
+"""
 input IStoreImage {
+  """
+  Image input URL.
+  """
   url: String!
+  """
+  Alias for the input image.
+  """
   alternateName: String!
 }

package/src/typeDefs/mutation.graphql

@@ -1,18 +1,46 @@
+"""
+Session information.
+"""
 type StoreSession {
+  """
+  Session channel.
+  """
   channel: String
+  """
+  Session country.
+  """
   country: String
+  """
+  Session postal code.
+  """
   postalCode: String
 }
 
+"""
+Session input.
+"""
 input IStoreSession {
+  """
+  Session input channel.
+  """
   channel: String
+  """
+  Session input country.
+  """
   country: String
+  """
+  Session input postal code.
+  """
   postalCode: String
 }
 
 type Mutation {
-  # Returns the order if anything changed with the order. Null if the order is valid
+  """
+  Returns the order if anything has changed in it, or `null` if the order is valid.
+  """
   validateCart(cart: IStoreCart!): StoreCart
-
+  """
+  Update session information.
+  """
   updateSession(session: IStoreSession!): StoreSession!
 }

package/src/typeDefs/offer.graphql

@@ -1,21 +1,71 @@
+"""
+Offer information.
+"""
 type StoreOffer {
+  """
+  This is displayed as the "from" price in the context of promotions' price comparison. This may change before it reaches the shelf.
+  """
   listPrice: Float!
+  """
+  Computed price before applying coupons, taxes or benefits. This may change before it reaches the shelf.
+  """
   sellingPrice: Float!
+  """
+  ISO code of the currency used for the offer prices.
+  """
   priceCurrency: String!
-  # Also known as spotPrice
+  """
+  Also known as spot price.
+  """
   price: Float!
+  """
+  Next date in which price is scheduled to change. If there is no scheduled change, this will be set a year in the future from current time.
+  """
   priceValidUntil: String!
+  """
+  Offer item condition.
+  """
   itemCondition: String!
+  """
+  Offer item availability.
+  """
   availability: String!
+  """
+  Seller responsible for the offer.
+  """
   seller: StoreOrganization!
+  """
+  Information on the item being offered.
+  """
   itemOffered: StoreProduct!
+  """
+  Number of items offered.
+  """
   quantity: Int!
 }
 
+"""
+Offer input.
+"""
 input IStoreOffer {
+  """
+  Also known as spot price.
+  """
   price: Float!
+  """
+  This is displayed as the "from" price in the context of promotions' price comparison. This may change before it reaches the shelf.
+  """
   listPrice: Float!
+  """
+  Seller responsible for the offer.
+  """
   seller: IStoreOrganization!
+  """
+  Information on the item being offered.
+  """
   itemOffered: IStoreProduct!
+  """
+  Number of items offered.
+  """
   quantity: Int!
 }