@faststore/api 4.5.0-dev.3 → 4.5.0-dev.4

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

@@ -18,8 +18,6 @@ import type {
   StoreContract,
   UserOrderFromList,
 } from '../../../__generated__/schema'
-import { getOrderEntryOperation } from './getOrderEntryOperation'
-import { getOrderFormItems } from './getOrderFormItems'
 import { recommendations } from './recommendations'
 import {
   BadRequestError,
@@ -33,6 +31,10 @@ import type { ProfileAddress } from '../clients/commerce/types/Profile'
 import type { SearchArgs } from '../clients/search'
 import type { ProductSearchResult } from '../clients/search/types/ProductSearchResult'
 import type { GraphqlContext } from '../index'
+import type {
+  ByLinkIdBrandRoot,
+  ByLinkIdCategoryRoot,
+} from '../loaders/collection'
 import { extractRuleForAuthorization } from '../utils/commercialAuth'
 import {
   mapSessionContractsToStoreContracts,
@@ -42,7 +44,7 @@ import {
 } from '../utils/contract'
 import { mutateChannelContext, mutateLocaleContext } from '../utils/contex'
 import { getAuthCookie, parseJwt } from '../utils/cookies'
-import { enhanceSku } from '../utils/enhanceSku'
+import { enhanceSku, type EnhancedSku } from '../utils/enhanceSku'
 import {
   findChannel,
   findCrossSelling,
@@ -51,10 +53,36 @@ import {
   findSlug,
   transformSelectedFacet,
 } from '../utils/facets'
+import { getCatalogLocale, isLocalizationEnabled } from '../utils/localization'
 import { isValidSkuId, pickBestSku } from '../utils/sku'
+import { slugify } from '../utils/slugify'
 import { SORT_MAP } from '../utils/sort'
 import { FACET_CROSS_SELLING_MAP } from './../utils/facets'
 import { StoreCollection } from './collection'
+import { getOrderEntryOperation } from './getOrderEntryOperation'
+import { getOrderFormItems } from './getOrderFormItems'
+import { getLocalizedProductEntry } from './product'
+
+/**
+ * Validates that a slug mismatch between IS linkText and the requested slug is
+ * actually a localized slug match. Fetches the localized product entry from
+ * Catalog Dataplane (with request-scoped caching) and checks whether the slug
+ * prefix matches the localized linkId for the current locale.
+ *
+ * Returns true if the slug is a valid localized match, false otherwise
+ * (including when the Dataplane API is unavailable).
+ */
+async function isLocalizedSlugMatch(
+  ctx: GraphqlContext,
+  slug: string,
+  productGroupID: string,
+  locale: string
+): Promise<boolean> {
+  const slugPrefix = slug.slice(0, slug.lastIndexOf('-'))
+  const entry = await getLocalizedProductEntry(ctx, productGroupID, locale)
+
+  return entry?.linkId === slugPrefix
+}
 
 const INVALID_SKU_ID_ERROR = 'Invalid SkuId'
 const SLUG_MISMATCH_ERROR =
@@ -66,6 +94,80 @@ const shouldFallbackToProductRoute = (error: unknown) =>
     (error.message === INVALID_SKU_ID_ERROR ||
       error.message.startsWith(SLUG_MISMATCH_ERROR)))
 
+/**
+ * Here be dragons 🦄🦄🦄
+ *
+ * In some cases, the slug has a valid skuId for a different product. This
+ * guards that the fetched sku is the one we actually asked for, throwing
+ * SLUG_MISMATCH_ERROR (caught by the caller) when it isn't.
+ *
+ * When localization is enabled, the slug prefix may be a localized LinkId
+ * that differs from the IS linkText (always in the default locale). In that
+ * case we validate against the Catalog Dataplane API before rejecting the
+ * slug.
+ */
+async function assertSkuMatchesSlug(
+  ctx: GraphqlContext,
+  sku: EnhancedSku,
+  slug: string | null | undefined,
+  locale: string | null | undefined
+): Promise<void> {
+  const { linkText, productId } = sku.isVariantOf
+
+  if (!slug || !linkText || slug.startsWith(linkText)) {
+    return
+  }
+
+  const isValidLocalizedMatch =
+    isLocalizationEnabled(ctx) &&
+    locale &&
+    isValidSkuId(slug.split('-').pop() ?? '') &&
+    (await isLocalizedSlugMatch(ctx, slug, productId, locale))
+
+  if (isValidLocalizedMatch) {
+    return
+  }
+
+  throw new Error(`${SLUG_MISMATCH_ERROR} slug: ${slug}, linkText: ${linkText}`)
+}
+
+/**
+ * Fallback used when the sku/slug lookup above fails (invalid skuId, not
+ * found, or slug mismatch): resolves the slug through the legacy pagetype
+ * route and fetches the product from Intelligent Search by id instead.
+ */
+async function fetchProductBySlugFallback(
+  ctx: GraphqlContext,
+  slug: string | null | undefined
+): Promise<EnhancedSku> {
+  if (slug == null) {
+    throw new BadRequestError('Missing slug or id')
+  }
+
+  const {
+    clients: { commerce, search },
+  } = ctx
+
+  const route = await commerce.catalog.portal.pagetype(`${slug}/p`)
+
+  if (route.pageType !== 'Product' || !route.id) {
+    throw new NotFoundError(`No product found for slug ${slug}`)
+  }
+
+  const product = await search
+    .fetchProduct({
+      field: 'id',
+      value: String(route.id),
+    })
+    .catch(() => null)
+
+  if (!product) {
+    throw new NotFoundError(`No product found for id ${route.id}`)
+  }
+
+  return enhanceSku(pickBestSku(product.items), product)
+}
+
 export const Query = {
   product: async (
     _: unknown,
@@ -88,7 +190,6 @@ export const Query = {
 
     const {
       loaders: { skuLoader },
-      clients: { commerce, search },
     } = ctx
 
     try {
@@ -100,22 +201,7 @@ export const Query = {
 
       const sku = await skuLoader.load(skuId)
 
-      /**
-       * Here be dragons 🦄🦄🦄
-       *
-       * In some cases, the slug has a valid skuId for a different
-       * product. This condition makes sure that the fetched sku
-       * is the one we actually asked for
-       * */
-      if (
-        slug &&
-        sku.isVariantOf.linkText &&
-        !slug.startsWith(sku.isVariantOf.linkText)
-      ) {
-        throw new Error(
-          `Slug was set but the fetched sku does not satisfy the slug condition. slug: ${slug}, linkText: ${sku.isVariantOf.linkText}`
-        )
-      }
+      await assertSkuMatchesSlug(ctx, sku, slug, locale)
 
       return sku
     } catch (err) {
@@ -123,30 +209,7 @@ export const Query = {
         throw err
       }
 
-      if (slug == null) {
-        throw new BadRequestError('Missing slug or id')
-      }
-
-      const route = await commerce.catalog.portal.pagetype(`${slug}/p`)
-
-      if (route.pageType !== 'Product' || !route.id) {
-        throw new NotFoundError(`No product found for slug ${slug}`)
-      }
-
-      const product = await search
-        .fetchProduct({
-          field: 'id',
-          value: String(route.id),
-        })
-        .catch(() => null)
-
-      if (!product) {
-        throw new NotFoundError(`No product found for id ${route.id}`)
-      }
-
-      const sku = pickBestSku(product.items)
-
-      return enhanceSku(sku, product)
+      return fetchProductBySlugFallback(ctx, slug)
     }
   },
   collection: (
@@ -158,7 +221,14 @@ export const Query = {
       loaders: { collectionLoader },
     } = ctx
 
-    return collectionLoader.load(slug)
+    // The request locale is set on ctx.storage.locale by the core `execute`
+    // wrapper (from Next.js i18n) rather than a GraphQL argument, so overridable
+    // fragments (API extensions) that also select `collection` keep merging
+    // without argument conflicts.
+    return collectionLoader.load({
+      slug,
+      locale: getCatalogLocale(ctx),
+    })
   },
   search: async (
     _: unknown,
@@ -323,25 +393,47 @@ export const Query = {
       commerce.catalog.category.tree(),
     ])
 
-    const categories: Array<CategoryTree & { level: number }> = []
-    const dfs = (node: CategoryTree, level: number) => {
-      categories.push({ ...node, level })
+    // Flatten the category tree. parentId is tracked per node so
+    // the type resolver can correctly classify Departments (fatherCategoryId: null)
+    // vs Categories (fatherCategoryId: number).
+    const categoryRoots: ByLinkIdCategoryRoot[] = []
+    const dfs = (node: CategoryTree, parentId: number | null) => {
+      categoryRoots.push({
+        id: node.id,
+        name: node.name,
+        fatherCategoryId: parentId,
+        linkId: slugify(node.name),
+        title: node.Title,
+        description: null,
+        metaTagDescription: node.MetaTagDescription,
+        availableLinkIds: null,
+        entityType: 'category' as const,
+        slug: new URL(node.url).pathname.slice(1).toLowerCase(),
+      })
 
       for (const child of node.children) {
-        dfs(child, level + 1)
+        dfs(child, node.id)
       }
     }
 
     for (const node of tree) {
-      dfs(node, 0)
+      dfs(node, null)
     }
 
-    const collections = [
-      ...brands
-        .filter((brand) => brand.isActive)
-        .map((x) => ({ ...x, type: 'brand' })),
-      ...categories,
-    ]
+    const brandRoots: ByLinkIdBrandRoot[] = brands
+      .filter((brand) => brand.isActive)
+      .map((brand) => ({
+        id: brand.id,
+        name: brand.name,
+        linkId: slugify(brand.name),
+        title: brand.title,
+        description: null,
+        metaTagDescription: brand.metaTagDescription,
+        availableLinkIds: null,
+        entityType: 'brand' as const,
+      }))
+
+    const collections = [...brandRoots, ...categoryRoots]
 
     const validCollections = collections
       // Nullable slugs may cause one route to override the other

package/src/platforms/vtex/typeDefs/collection.graphql

@@ -1,5 +1,8 @@
 """
-Product collection type. Possible values are `Department`, `Category`, `Brand`, `Cluster`, `SubCategory` or `Collection`.
+Product collection type. Possible values are `Department`, `Category`, `Brand` or `Collection`.
+
+`SubCategory` and `Cluster` are still declared for backward compatibility but are
+deprecated and never returned.
 """
 enum StoreCollectionType {
   """
@@ -12,16 +15,26 @@ enum StoreCollectionType {
   Category
   """
   Third level of product categorization.
+
+  Deprecated: never returned — third-level categories resolve as `Category`.
   """
   SubCategory
+    @deprecated(
+      reason: "Never returned since the by-linkid migration: the category response only exposes `fatherCategoryId`, which distinguishes root from non-root but not tree depth, so third-level categories resolve as `Category`. Scheduled for removal in the next major."
+    )
   """
   Product brand.
   """
   Brand
   """
   Product cluster.
+
+  Deprecated: never returned — clusters resolve as `Collection`.
   """
   Cluster
+    @deprecated(
+      reason: "Never returned since the by-linkid migration: clusters and curated collections are both served by `collection/by-linkid`, whose response carries no discriminator between them, so both resolve as `Collection`. Scheduled for removal in the next major."
+    )
   """
   Product collection.
   """
@@ -80,4 +93,23 @@ type StoreCollection {
   Collection type.
   """
   type: StoreCollectionType!
+  """
+  Localized versions of this collection for all available locales.
+  Only populated when localization is enabled.
+  """
+  otherLocales: [StoreCollectionLocale!]
+}
+
+"""
+Localized collection data for a specific locale.
+"""
+type StoreCollectionLocale {
+  """
+  Locale code (e.g. "pt-BR", "it-IT").
+  """
+  locale: String!
+  """
+  Localized collection slug (e.g. "vestuario/camisetas").
+  """
+  slug: String!
 }

package/src/platforms/vtex/typeDefs/product.graphql

@@ -94,6 +94,25 @@ type StoreProduct {
   Delivery Promise product's badge.
   """
   deliveryPromiseBadges: [DeliveryPromiseBadge]
+  """
+  Localized versions of this product for all available locales.
+  Only populated when localization is enabled.
+  """
+  otherLocales: [StoreProductLocale!]
+}
+
+"""
+Localized product data for a specific locale.
+"""
+type StoreProductLocale {
+  """
+  Locale code (e.g. "pt-BR", "it-IT").
+  """
+  locale: String!
+  """
+  Localized product slug including the SKU ID suffix (e.g. "adidas-polo-uomo-65").
+  """
+  slug: String!
 }
 
 type SkuSpecification {

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

@@ -0,0 +1,45 @@
+import type { GraphqlContext } from '..'
+
+export interface LocalizationConfig {
+  enabled?: boolean
+  defaultLocale?: string
+  locales?: Record<string, unknown>
+}
+
+export const getLocalizationConfig = (
+  ctx: GraphqlContext
+): LocalizationConfig =>
+  (ctx.discoveryConfig as { localization?: LocalizationConfig } | undefined)
+    ?.localization ?? {}
+
+export const isLocalizationEnabled = (ctx: GraphqlContext): boolean =>
+  getLocalizationConfig(ctx).enabled === true
+
+export const getConfiguredLocales = (ctx: GraphqlContext): string[] =>
+  Object.keys(getLocalizationConfig(ctx).locales ?? {})
+
+export const getDefaultLocale = (ctx: GraphqlContext): string | undefined =>
+  getLocalizationConfig(ctx).defaultLocale
+
+/**
+ * Whether `locale` is one of the store's configured locales. Used to validate
+ * client-supplied locale input before propagating it to downstream platform
+ * APIs. Returns false when localization is disabled (no configured locales).
+ */
+export const isConfiguredLocale = (
+  ctx: GraphqlContext,
+  locale: string
+): boolean => getConfiguredLocales(ctx).includes(locale)
+
+/**
+ * Locale to forward to Catalog by-linkid endpoints via the Accept-Language
+ * header so they return localized name/title/description. Returns the active
+ * locale only when localization is enabled; otherwise `undefined`, so
+ * non-localized stores send no header and falls back to the store's default
+ * registered language (legacy behavior).
+ *
+ * Read at request time (not client construction) because `ctx.storage.locale`
+ * is mutated later by the collection resolver.
+ */
+export const getCatalogLocale = (ctx: GraphqlContext): string | undefined =>
+  isLocalizationEnabled(ctx) ? ctx.storage.locale || undefined : undefined