@faststore/api 1.8.22 → 1.8.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faststore/api",
-  "version": "1.8.22",
+  "version": "1.8.25",
   "license": "MIT",
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",
@@ -45,5 +45,5 @@
   "peerDependencies": {
     "graphql": "^15.6.0"
   },
-  "gitHead": "8feb71286b28d2308d4b11b37dbb62c2d5c76838"
+  "gitHead": "da2e248b5446eea91fe96e96e6f7028d2ab79c45"
 }

package/src/__generated__/schema.ts

@@ -11,7 +11,7 @@ export type Scalars = {
   Float: number;
 };
 
-/** Shopping cart identification input. */
+/** Shopping cart input. */
 export type IStoreCart = {
   /** Order information, including `orderNumber` and `acceptedOffer`. */
   order: IStoreOrder;
@@ -43,7 +43,7 @@ export type IStoreOffer = {
 export type IStoreOrder = {
   /** Array with information on each accepted offer. */
   acceptedOffer: Array<IStoreOffer>;
-  /** Order shopping cart ID, also known as `orderFormId`. */
+  /** ID of the order in [VTEX order management](https://help.vtex.com/en/tutorial/license-manager-resources-oms--60QcBsvWeum02cFi3GjBzg#). */
   orderNumber: Scalars['String'];
 };
 
@@ -53,13 +53,13 @@ export type IStoreOrganization = {
   identifier: Scalars['String'];
 };
 
-/** Product input. */
+/** Product input. Products are variants within product groups, equivalent to VTEX [SKUs](https://help.vtex.com/en/tutorial/what-is-an-sku--1K75s4RXAQyOuGUYKMM68u#). For example, you may have a **Shirt** product group with associated products such as **Blue shirt size L**, **Green shirt size XL** and so on. */
 export type IStoreProduct = {
   /** Array of product images. */
   image: Array<IStoreImage>;
   /** Product name. */
   name: Scalars['String'];
-  /** Stock Keeping Unit ID. */
+  /** Stock Keeping Unit. Merchant-specific ID for the product. */
   sku: Scalars['String'];
 };
 
@@ -350,7 +350,7 @@ export type StoreOrder = {
   __typename?: 'StoreOrder';
   /** Array with information on each accepted offer. */
   acceptedOffer: Array<StoreOffer>;
-  /** Order shopping cart ID, also known as `orderFormId`. */
+  /** ID of the order in [VTEX order management](https://help.vtex.com/en/tutorial/license-manager-resources-oms--60QcBsvWeum02cFi3GjBzg#). */
   orderNumber: Scalars['String'];
 };
 
@@ -389,7 +389,7 @@ export type StorePerson = {
   id: Scalars['String'];
 };
 
-/** Product information. */
+/** Product information. Products are variants within product groups, equivalent to VTEX [SKUs](https://help.vtex.com/en/tutorial/what-is-an-sku--1K75s4RXAQyOuGUYKMM68u#). For example, you may have a **Shirt** product group with associated products such as **Blue shirt size L**, **Green shirt size XL** and so on. */
 export type StoreProduct = {
   __typename?: 'StoreProduct';
   /** Array of additional properties. */
@@ -412,13 +412,13 @@ export type StoreProduct = {
   name: Scalars['String'];
   /** Aggregate offer information. */
   offers: StoreAggregateOffer;
-  /** Product ID. */
+  /** Product ID, such as [ISBN](https://www.isbn-international.org/content/what-isbn) or similar global IDs. */
   productID: Scalars['String'];
   /** Array with review information. */
   review: Array<StoreReview>;
   /** Meta tag data. */
   seo: StoreSeo;
-  /** Stock Keeping Unit ID. */
+  /** Stock Keeping Unit. Merchant-specific ID for the product. */
   sku: Scalars['String'];
   /** Corresponding collection URL slug, with which to retrieve this entity. */
   slug: Scalars['String'];
@@ -442,12 +442,12 @@ export type StoreProductEdge = {
   node: StoreProduct;
 };
 
-/** Product group information. */
+/** Product group information. Product groups are catalog entities that may contain variants. They are equivalent to VTEX [Products](https://help.vtex.com/en/tutorial/what-is-a-product--2zrB2gFCHyQokCKKE8kuAw#), whereas each variant is equivalent to a VTEX [SKU](https://help.vtex.com/en/tutorial/what-is-an-sku--1K75s4RXAQyOuGUYKMM68u#). For example, you may have a **Shirt** product group with associated products such as **Blue shirt size L**, **Green shirt size XL** and so on. */
 export type StoreProductGroup = {
   __typename?: 'StoreProductGroup';
   /** Array of additional properties. */
   additionalProperty: Array<StorePropertyValue>;
-  /** Array of variants related to product group. */
+  /** Array of variants related to product group. Variants are equivalent to VTEX [SKUs](https://help.vtex.com/en/tutorial/what-is-an-sku--1K75s4RXAQyOuGUYKMM68u#). */
   hasVariant: Array<StoreProduct>;
   /** Product group name. */
   name: Scalars['String'];

package/src/platforms/vtex/clients/commerce/index.ts

@@ -103,6 +103,26 @@ export const VtexCommerce = (
           }
         )
       },
+      setCustomData: ({
+        id,
+        appId,
+        key,
+        value,
+      }: {
+        id: string
+        appId: string
+        key: string
+        value: string
+      }): Promise<OrderForm> => {
+        return fetchAPI(
+          `${base}/api/checkout/pub/orderForm/${id}/customData/${appId}/${key}`,
+          {
+            ...BASE_INIT,
+            body: JSON.stringify({ value }),
+            method: 'PUT',
+          }
+        )
+      },
       region: async ({
         postalCode,
         country,

package/src/platforms/vtex/clients/commerce/types/OrderForm.ts

@@ -136,7 +136,7 @@ export interface OrderForm {
   giftRegistryData: any | null
   openTextField: any | null
   invoiceData: any | null
-  customData: any | null
+  customData: OrderFormCustomData | null
   itemMetadata: {
     items: MetadataItem[]
   }
@@ -149,6 +149,14 @@ export interface OrderForm {
   itemsOrdination: any | null
 }
 
+export interface OrderFormCustomData {
+  customApps: Array<{
+    fields: Record<string, string>
+    id: string
+    major: number
+  }>
+}
+
 export interface OrderFormMarketingData {
   utmCampaign?: string
   utmMedium?: string

package/src/platforms/vtex/index.ts

@@ -25,6 +25,11 @@ export interface Options {
   // Default sales channel to use for fetching products
   channel: string
   hideUnavailableItems: boolean
+  flags?: FeatureFlags
+}
+
+interface FeatureFlags {
+  enableOrderFormSync?: boolean
 }
 
 export interface Context {
@@ -38,6 +43,7 @@ export interface Context {
    * */
   storage: {
     channel: Required<Channel>
+    flags: FeatureFlags
   }
   headers: Record<string, string>
 }
@@ -68,6 +74,7 @@ const Resolvers = {
 export const getContextFactory = (options: Options) => (ctx: any): Context => {
   ctx.storage = {
     channel: ChannelMarshal.parse(options.channel),
+    flags: options.flags ?? {},
   }
   ctx.clients = getClients(options, ctx)
   ctx.loaders = getLoaders(options, ctx)

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

@@ -1,5 +1,6 @@
 import { enhanceCommercialOffer } from '../utils/enhanceCommercialOffer'
 import { bestOfferFirst } from '../utils/productStock'
+import { slugify } from '../utils/slugify'
 import type { EnhancedCommercialOffer } from '../utils/enhanceCommercialOffer'
 import type { Resolver } from '..'
 import type { PromiseType } from '../../../typings'
@@ -38,11 +39,13 @@ export const StoreProduct: Record<string, Resolver<Root>> & {
     return {
       itemListElement: [
         ...categories.reverse().map((categoryPath, index) => {
-          const categoryNames = categoryPath.split('/')
+          const splitted = categoryPath.split('/')
+          const name = splitted[splitted.length - 2]
+          const item = splitted.map(slugify).join('/')
 
           return {
-            name: categoryNames[categoryNames.length - 2],
-            item: categoryPath.toLowerCase(),
+            name,
+            item,
             position: index + 1,
           }
         }),

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

@@ -1,14 +1,15 @@
 import deepEquals from 'fast-deep-equal'
 
+import { md5 } from '../utils/md5'
 import type {
-  IStoreOrder,
   IStoreCart,
   IStoreOffer,
+  IStoreOrder,
 } from '../../../__generated__/schema'
 import type {
   OrderForm,
-  OrderFormItem,
   OrderFormInputItem,
+  OrderFormItem,
 } from '../clients/commerce/types/OrderForm'
 import type { Context } from '..'
 
@@ -69,6 +70,70 @@ const equals = (storeOrder: IStoreOrder, orderForm: OrderForm) => {
   return isSameOrder && orderItemsAreSync
 }
 
+const orderFormToCart = (
+  form: OrderForm,
+  skuLoader: Context['loaders']['skuLoader']
+) => {
+  return {
+    order: {
+      orderNumber: form.orderFormId,
+      acceptedOffer: form.items.map((item) => ({
+        ...item,
+        product: skuLoader.load([{ key: 'id', value: item.id }]), // TODO: add channel
+      })),
+    },
+    messages: form.messages.map(({ text, status }) => ({
+      text,
+      status: status.toUpperCase(),
+    })),
+  }
+}
+
+const getOrderFormEtag = ({ items }: OrderForm) => md5(JSON.stringify(items))
+
+const setOrderFormEtag = async (
+  form: OrderForm,
+  commerce: Context['clients']['commerce']
+) => {
+  try {
+    const orderForm = await commerce.checkout.setCustomData({
+      id: form.orderFormId,
+      appId: 'faststore',
+      key: 'cartEtag',
+      value: getOrderFormEtag(form),
+    })
+
+    return orderForm
+  } catch (err) {
+    console.error(
+      'Error while setting custom data to orderForm.\n Make sure to add the following custom app to the orderForm: \n{"fields":["cartEtag"],"id":"faststore","major":1}.\n More info at: https://developers.vtex.com/vtex-rest-api/docs/customizable-fields-with-checkout-api'
+    )
+
+    throw err
+  }
+}
+
+/**
+ * Checks if cartEtag stored on customData is up to date
+ * @description If cartEtag is not up to date, this means that
+ * another system changed the cart, like Checkout UI or Order Placed
+ */
+const isOrderFormStale = (form: OrderForm) => {
+  const faststoreData = form.customData?.customApps.find(
+    (app) => app.id === 'faststore'
+  )
+
+  const oldEtag = faststoreData?.fields?.cartEtag
+
+  if (oldEtag == null) {
+    return true
+  }
+
+  const newEtag = getOrderFormEtag(form)
+
+  return newEtag !== oldEtag
+}
+
 /**
  * This resolver implements the optimistic cart behavior. The main idea in here
  * is that we receive a cart from the UI (as query params) and we validate it with
@@ -87,6 +152,7 @@ export const validateCart = async (
   { cart: { order } }: { cart: IStoreCart },
   ctx: Context
 ) => {
+  const { enableOrderFormSync } = ctx.storage.flags
   const { orderNumber, acceptedOffer } = order
   const {
     clients: { commerce },
@@ -98,6 +164,19 @@ export const validateCart = async (
     id: orderNumber,
   })
 
+  // Step1.5: Check if another system changed the orderForm with this orderNumber
+  // If so, this means the user interacted with this cart elsewhere and expects
+  // to see this new cart state instead of what's stored on the user's browser.
+  if (enableOrderFormSync === true) {
+    const isStale = isOrderFormStale(orderForm)
+
+    if (isStale === true && orderNumber) {
+      const newOrderForm = await setOrderFormEtag(orderForm, commerce)
+
+      return orderFormToCart(newOrderForm, skuLoader)
+    }
+  }
+
   // Step2: Process items from both browser and checkout so they have the same shape
   const browserItemsById = groupById(acceptedOffer)
   const originItemsById = groupById(orderForm.items.map(orderFormItemToOffer))
@@ -139,28 +218,22 @@ export const validateCart = async (
   }
 
   // Step4: Apply delta changes to order form
-  const updatedOrderForm = await commerce.checkout.updateOrderFormItems({
-    id: orderForm.orderFormId,
-    orderItems: changes,
-  })
+  const updatedOrderForm = await commerce.checkout
+    // update orderForm items
+    .updateOrderFormItems({
+      id: orderForm.orderFormId,
+      orderItems: changes,
+    })
+    // update orderForm etag so we know last time we touched this orderForm
+    .then((form) =>
+      enableOrderFormSync ? setOrderFormEtag(form, commerce) : form
+    )
 
   // Step5: If no changes detected before/after updating orderForm, the order is validated
   if (equals(order, updatedOrderForm)) {
     return null
   }
 
-  // Step6: There were changes, convert orderForm to StoreOrder
-  return {
-    order: {
-      orderNumber: updatedOrderForm.orderFormId,
-      acceptedOffer: updatedOrderForm.items.map((item) => ({
-        ...item,
-        product: skuLoader.load([{ key: 'id', value: item.id }]), // TODO: add channel
-      })),
-    },
-    messages: updatedOrderForm.messages.map(({ text, status }) => ({
-      text,
-      status: status.toUpperCase(),
-    })),
-  }
+  // Step6: There were changes, convert orderForm to StoreCart
+  return orderFormToCart(updatedOrderForm, skuLoader)
 }

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

@@ -0,0 +1,4 @@
+import crypto from 'crypto'
+
+export const md5 = (payload: string) =>
+  crypto.createHash('md5').update(payload).digest('hex')

package/src/typeDefs/cart.graphql

@@ -27,7 +27,7 @@ type StoreCart {
 }
 
 """
-Shopping cart identification input.
+Shopping cart input.
 """
 input IStoreCart {
   """

package/src/typeDefs/order.graphql

@@ -3,7 +3,7 @@ Information of a specific order.
 """
 type StoreOrder {
   """
-  Order shopping cart ID, also known as `orderFormId`.
+  ID of the order in [VTEX order management](https://help.vtex.com/en/tutorial/license-manager-resources-oms--60QcBsvWeum02cFi3GjBzg#).
   """
   orderNumber: String!
   """
@@ -17,7 +17,7 @@ Offer input.
 """
 input IStoreOrder {
   """
-  Order shopping cart ID, also known as `orderFormId`.
+  ID of the order in [VTEX order management](https://help.vtex.com/en/tutorial/license-manager-resources-oms--60QcBsvWeum02cFi3GjBzg#).
   """
   orderNumber: String!
   """

package/src/typeDefs/product.graphql

@@ -1,5 +1,5 @@
 """
-Product information.
+Product information. Products are variants within product groups, equivalent to VTEX [SKUs](https://help.vtex.com/en/tutorial/what-is-an-sku--1K75s4RXAQyOuGUYKMM68u#). For example, you may have a **Shirt** product group with associated products such as **Blue shirt size L**, **Green shirt size XL** and so on.
 """
 type StoreProduct {
   """
@@ -19,7 +19,7 @@ type StoreProduct {
   """
   name: String!
   """
-  Product ID.
+  Product ID, such as [ISBN](https://www.isbn-international.org/content/what-isbn) or similar global IDs.
   """
   productID: String!
   """
@@ -39,7 +39,7 @@ type StoreProduct {
   """
   offers: StoreAggregateOffer!
   """
-  Stock Keeping Unit ID.
+  Stock Keeping Unit. Merchant-specific ID for the product.
   """
   sku: String!
   """
@@ -65,11 +65,11 @@ type StoreProduct {
 }
 
 """
-Product input.
+Product input. Products are variants within product groups, equivalent to VTEX [SKUs](https://help.vtex.com/en/tutorial/what-is-an-sku--1K75s4RXAQyOuGUYKMM68u#). For example, you may have a **Shirt** product group with associated products such as **Blue shirt size L**, **Green shirt size XL** and so on.
 """
 input IStoreProduct {
   """
-  Stock Keeping Unit ID.
+  Stock Keeping Unit. Merchant-specific ID for the product.
   """
   sku: String!
   """

package/src/typeDefs/productGroup.graphql

@@ -1,9 +1,9 @@
 """
-Product group information.
+Product group information. Product groups are catalog entities that may contain variants. They are equivalent to VTEX [Products](https://help.vtex.com/en/tutorial/what-is-a-product--2zrB2gFCHyQokCKKE8kuAw#), whereas each variant is equivalent to a VTEX [SKU](https://help.vtex.com/en/tutorial/what-is-an-sku--1K75s4RXAQyOuGUYKMM68u#). For example, you may have a **Shirt** product group with associated products such as **Blue shirt size L**, **Green shirt size XL** and so on.
 """
 type StoreProductGroup {
   """
-  Array of variants related to product group.
+  Array of variants related to product group. Variants are equivalent to VTEX [SKUs](https://help.vtex.com/en/tutorial/what-is-an-sku--1K75s4RXAQyOuGUYKMM68u#).
   """
   hasVariant: [StoreProduct!]!
   """