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

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

@@ -2,71 +2,117 @@ import type { GraphqlResolver } from '..'
 import type { Brand } from '../clients/commerce/types/Brand'
 import type { CategoryTree } from '../clients/commerce/types/CategoryTree'
 import type { CollectionPageType } from '../clients/commerce/types/Portal'
-import { isCollectionPageType } from '../loaders/collection'
+import {
+  isBrand,
+  isCategory,
+  isCollection,
+  type ByLinkIdBrandRoot,
+  type ByLinkIdCategoryRoot,
+  type ByLinkIdCollectionRoot,
+} from '../loaders/collection'
+import { getCatalogLocale, getLocalizationConfig } from '../utils/localization'
 import { slugify } from '../utils/slugify'
 
-export type Root =
+type ByLinkIdRoot =
+  | ByLinkIdCategoryRoot
+  | ByLinkIdBrandRoot
+  | ByLinkIdCollectionRoot
+
+/**
+ * @deprecated Legacy pagetype-based shape. It is no longer produced at runtime
+ * since the by-linkid migration and only remains in the public `Root` union to
+ * avoid a breaking change for stores that still reference `StoreCollectionRoot`.
+ *
+ * TODO: remove in the next major of `@faststore/api` (drop from the `Root`
+ * union below) — this is a breaking change and must ship with a BREAKING CHANGE note.
+ */
+export type LegacyStoreCollectionRoot =
   | Brand
   | (CategoryTree & { level: number })
   | CollectionPageType
 
-const isBrand = (x: any): x is Brand | CollectionPageType =>
-  x.type === 'brand' ||
-  (isCollectionPageType(x) && x.pageType.toLowerCase() === 'brand')
-
-const isCollection = (x: Root): x is CollectionPageType =>
-  isCollectionPageType(x) && x.pageType.toLowerCase() === 'collection'
+/**
+ * Public `StoreCollectionRoot` type (re-exported from the package entrypoint).
+ * Kept as a backward-compatible superset: the legacy members are retained
+ * (see {@link LegacyStoreCollectionRoot}) so existing consumers keep compiling,
+ * while `ByLinkIdRoot` reflects the real runtime shape.
+ */
+export type Root = ByLinkIdRoot | LegacyStoreCollectionRoot
 
-const slugifyRoot = (root: Root) => {
-  if (isBrand(root) || isCollection(root)) {
-    return slugify(root.name)
+const slugifyRoot = (root: ByLinkIdRoot): string => {
+  if (isCategory(root)) {
+    // root.slug is the full accumulated input slug (e.g. "vestuario/camisetas"),
+    // injected by the loader — no URL parsing needed.
+    return root.slug
   }
 
-  if (isCollectionPageType(root)) {
-    return new URL(`https://${root.url}`).pathname.slice(1).toLowerCase()
+  if (isBrand(root)) {
+    return root.linkId
   }
 
-  return new URL(root.url).pathname.slice(1).toLowerCase()
+  // collection — linkId may be null for clusters not yet registered in multilanguage
+  return root.linkId ?? slugify(root.name)
 }
 
-export const StoreCollection: Record<string, GraphqlResolver<Root>> = {
+export const StoreCollection: Record<string, GraphqlResolver<ByLinkIdRoot>> = {
   id: ({ id }) => id.toString(),
   slug: (root) => slugifyRoot(root),
-  seo: (root) =>
-    isBrand(root) || isCollectionPageType(root)
-      ? {
-          title: root.title ?? root.name,
-          description: root.metaTagDescription,
-        }
-      : {
-          title: root.Title,
-          description: root.MetaTagDescription,
-        },
-  type: (root) =>
-    isBrand(root)
-      ? 'Brand'
-      : isCollectionPageType(root)
-        ? root.pageType
-        : root.level === 0
-          ? 'Department'
-          : 'Category',
-  meta: (root) => {
+  seo: (root) => ({
+    title: root.title ?? root.name,
+    // pagetype.metaTagDescription and catalog `description` share the same
+    // source (confirmed with Catalog). Prefer metaTagDescription when present
+    // for forward-compat; fall back to description for by-linkid parity.
+    description: root.metaTagDescription ?? root.description,
+  }),
+  type: (root) => {
+    if (isBrand(root)) return 'Brand'
+    // Clusters and curated collections share the collection/by-linkid endpoint,
+    // whose response has no discriminator between them, so both report as
+    // 'Collection'. The enum still declares 'Cluster' for backward compat.
+    if (isCollection(root)) return 'Collection'
+    // Department = root category (no parent); Category = everything else.
+    // SubCategory distinction (3rd level+) requires recursive parent lookup — deferred.
+    return root.fatherCategoryId === null ? 'Department' : 'Category'
+  },
+  meta: async (root, _, ctx) => {
     const slug = slugifyRoot(root)
 
-    return isBrand(root)
-      ? {
-          selectedFacets: [{ key: 'brand', value: slug }],
-        }
-      : isCollection(root)
-        ? {
-            selectedFacets: [{ key: 'productclusterids', value: root.id }],
-          }
-        : {
-            selectedFacets: slug.split('/').map((segment, index) => ({
-              key: `category-${index + 1}`,
-              value: segment,
-            })),
-          }
+    if (isBrand(root)) {
+      return { selectedFacets: [{ key: 'brand', value: slug }] }
+    }
+
+    if (isCollection(root)) {
+      return { selectedFacets: [{ key: 'productclusterids', value: root.id }] }
+    }
+
+    // For categories, IS expects the canonical (default-locale) slug in selectedFacets
+    // regardless of which locale the current request uses. The by-linkid API echoes the
+    // queried slug in `linkId`, so we resolve canonical via availableLinkIds[defaultLocale].
+    const { defaultLocale } = getLocalizationConfig(ctx)
+
+    const segments = slug.split('/').filter(Boolean)
+    const segmentSlugs = segments.map((_, i) =>
+      segments.slice(0, i + 1).join('/')
+    )
+
+    const {
+      loaders: { collectionLoader },
+    } = ctx
+
+    const entities = await Promise.all(
+      segmentSlugs.map((s) =>
+        collectionLoader.load({ slug: s, locale: getCatalogLocale(ctx) })
+      )
+    )
+
+    return {
+      selectedFacets: entities.map((entity, index) => ({
+        key: `category-${index + 1}`,
+        value:
+          (defaultLocale && entity.availableLinkIds?.[defaultLocale]) ||
+          entity.linkId,
+      })),
+    }
   },
   breadcrumbList: async (root, _, ctx) => {
     const {
@@ -76,36 +122,97 @@ export const StoreCollection: Record<string, GraphqlResolver<Root>> = {
     const slug = slugifyRoot(root)
 
     /**
-     * Split slug into segments so we fetch all data for
-     * the breadcrumb. For instance, if we get `/foo/bar`
-     * we need all metadata for both `/foo` and `/bar` and
-     * thus we need to fetch pageType for `/foo` and `/bar`
+     * Split slug into segments so each breadcrumb level gets its own
+     * by-linkid result. For "vestuario/camisetas" this produces two loader
+     * calls: one for "vestuario" and one for "vestuario/camisetas".
      */
-    const segments = slug.split('/').filter((segment) => Boolean(segment))
-    const slugs = segments.map((__, index) =>
+    const segments = slug.split('/').filter(Boolean)
+    const slugs = segments.map((_, index) =>
       segments.slice(0, index + 1).join('/')
     )
 
-    const collections: (CollectionPageType & {
-      slug: string
-    })[] = await Promise.all(
-      slugs.map(async (s) => {
-        const collection = await collectionLoader.load(s)
-        return { slug: s, ...collection }
-      })
+    const collections = await Promise.all(
+      slugs.map((s) =>
+        collectionLoader.load({ slug: s, locale: getCatalogLocale(ctx) })
+      )
     )
 
     return {
       itemListElement: collections.map((collection, index) => ({
-        item: isCollection(collection)
-          ? `/${collection.slug}`
-          : new URL(
-              `https://${(collection as CollectionPageType).url}`
-            ).pathname.toLowerCase(),
+        item: `/${slugifyRoot(collection)}`,
         name: collection.name,
         position: index + 1,
       })),
       numberOfItems: collections.length,
     }
   },
+
+  otherLocales: async (root, _, ctx) => {
+    const localizationConfig = getLocalizationConfig(ctx)
+
+    if (!localizationConfig.enabled) return null
+
+    const configuredLocales = Object.keys(localizationConfig.locales ?? {})
+
+    if (configuredLocales.length === 0) return null
+
+    const currentLocale = ctx.storage.locale
+    const slug = slugifyRoot(root)
+    const segments = slug.split('/').filter(Boolean)
+
+    if (segments.length === 0) return null
+
+    const {
+      loaders: { collectionLoader },
+    } = ctx
+
+    // Build per-level slug paths: ["vestuario", "vestuario/camisetas"].
+    // The collectionLoader DataLoader cache means any segment already fetched
+    // by breadcrumbList or meta costs nothing here.
+    const segmentSlugs = segments.map((_, i) =>
+      segments.slice(0, i + 1).join('/')
+    )
+
+    let entities: ByLinkIdRoot[]
+
+    try {
+      entities = await Promise.all(
+        segmentSlugs.map((s) =>
+          collectionLoader.load({ slug: s, locale: getCatalogLocale(ctx) })
+        )
+      )
+    } catch (err) {
+      console.warn('[otherLocales] failed to load collection entities:', err)
+
+      return null
+    }
+
+    return configuredLocales
+      .map((configuredLocale) => {
+        if (configuredLocale === currentLocale) {
+          // The input slug is already the localized path for the current locale.
+          return { locale: configuredLocale, slug }
+        }
+
+        // Build the full path by joining each segment's localized linkId from
+        // availableLinkIds. For the default locale, the canonical slug is also
+        // present in availableLinkIds.
+        // If any segment is missing an entry for this locale, omit the whole URL
+        // to keep the hreflang cluster symmetric.
+        const parts: string[] = []
+
+        for (const entity of entities) {
+          const linkId = entity.availableLinkIds?.[configuredLocale]
+
+          if (!linkId) return null
+
+          parts.push(linkId)
+        }
+
+        return parts.length > 0
+          ? { locale: configuredLocale, slug: parts.join('/') }
+          : null
+      })
+      .filter((e): e is { locale: string; slug: string } => e !== null)
+  },
 }

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

@@ -1,9 +1,15 @@
-import type { GraphqlResolver } from '..'
+import type { GraphqlContext, GraphqlResolver } from '..'
 import type { StoreImage, StoreProductImageArgs } from '../../..'
+import type { LocalizedProductEntry } from '../clients/catalog'
 import type { Attachment } from '../clients/commerce/types/OrderForm'
 import { canonicalFromProduct } from '../utils/canonical'
 import type { EnhancedCommercialOffer } from '../utils/enhanceCommercialOffer'
 import { enhanceCommercialOffer } from '../utils/enhanceCommercialOffer'
+import {
+  getConfiguredLocales,
+  getDefaultLocale,
+  isLocalizationEnabled,
+} from '../utils/localization'
 import { bestOfferFirst } from '../utils/productStock'
 import {
   attachmentToPropertyValue,
@@ -36,6 +42,50 @@ function removeTrailingSlashes(path: string) {
   return path.replace(/^\/+|\/+$/g, '')
 }
 
+/**
+ * Returns a cached-or-fetched localized product entry from the Catalog Dataplane.
+ * The promise is stored in `ctx.storage.productTranslationsCache` so it is shared
+ * across the `breadcrumbList`, `otherLocales`, and slug-validation resolvers within
+ * the same request.
+ *
+ * The in-flight promise (not just the resolved value) is cached so concurrent
+ * sibling resolvers dedupe to a single Catalog Dataplane request instead of each
+ * missing the cache and issuing a duplicate fetch.
+ */
+export async function getLocalizedProductEntry(
+  ctx: GraphqlContext,
+  productId: string,
+  locale: string
+): Promise<LocalizedProductEntry | null> {
+  const cacheKey = `${productId}:${locale}`
+  ctx.storage.productTranslationsCache ??= new Map()
+  const cache = ctx.storage.productTranslationsCache
+
+  const cached = cache.get(cacheKey)
+  if (cached) return cached
+
+  const entry = (async (): Promise<LocalizedProductEntry | null> => {
+    try {
+      const result = await ctx.clients.catalog.getLocalizedProduct(
+        productId,
+        locale
+      )
+
+      return {
+        linkId: result.linkId,
+        categories: result.categories ?? [],
+        availableLinkIds: result.availableLinkIds ?? {},
+      }
+    } catch {
+      return null
+    }
+  })()
+
+  cache.set(cacheKey, entry)
+
+  return entry
+}
+
 /**
  * Finds the index of the main category tree that matches the given category ID.
  * This avoids including similar categories in the breadcrumb list.
@@ -77,20 +127,74 @@ export const StoreProduct: Record<string, GraphqlResolver<Root>> & {
   }),
   brand: ({ isVariantOf: { brand } }) => ({ name: brand }),
   unitMultiplier: ({ unitMultiplier }) => unitMultiplier,
-  breadcrumbList: ({
-    isVariantOf: {
-      categories,
-      productName,
-      linkText,
-      categoryId,
-      categoriesIds,
-    },
-    itemId,
-  }) => {
+  breadcrumbList: async (root, _args, ctx) => {
+    const {
+      isVariantOf: {
+        categories,
+        productName,
+        linkText,
+        categoryId,
+        categoriesIds,
+        productId,
+      },
+      itemId,
+    } = root
+
     const mainTreeIndex = findMainTreeIndex(categoriesIds, categoryId)
     const mainTree = categories[mainTreeIndex]
     const splittedCategories = removeTrailingSlashes(mainTree).split('/')
 
+    const locale = ctx.storage.locale
+
+    if (isLocalizationEnabled(ctx) && locale) {
+      const entry = await getLocalizedProductEntry(ctx, productId, locale)
+
+      if (entry) {
+        // Extract the category IDs that belong to the main tree (same tree chosen from IS above).
+        // A product can be registered in multiple trees; Catalog Dataplane returns all of them
+        // in categories[], so we filter to only the ones matching this tree's IDs.
+        const mainTreeIds = new Set(
+          removeTrailingSlashes(categoriesIds[mainTreeIndex])
+            .split('/')
+            .filter(Boolean)
+        )
+
+        const localizedCategories = entry.categories
+          .filter((category) => mainTreeIds.has(category.id.toString()))
+          .sort(
+            (a, b) =>
+              a.fullPath.split('/').length - b.fullPath.split('/').length
+          )
+
+        // Length guard: if Catalog Dataplane returns fewer categories than IS expects
+        // (e.g. data inconsistency or empty categories), fall through to the IS fallback.
+        const hasAllBreadcrumbLevels =
+          localizedCategories.length === splittedCategories.length
+        if (hasAllBreadcrumbLevels) {
+          return {
+            itemListElement: [
+              // Category items: both name and slug come from Catalog Dataplane, ensuring
+              // they are always consistent with each other for the requested locale.
+              ...localizedCategories.map((category, index) => ({
+                name: category.name,
+                item: `/${category.fullPathUriName}/`,
+                position: index + 1,
+              })),
+              {
+                name: productName,
+                item: getPath(entry.linkId, itemId),
+                position: splittedCategories.length + 1,
+              },
+            ],
+            numberOfItems: splittedCategories.length,
+          }
+        }
+      }
+    }
+
+    // Fallback: localization disabled, Catalog Dataplane unavailable, or category count mismatch.
+    // Builds paths by applying slugify() to the IS category names, which mirrors the behaviour
+    // of the VTEX Rewriter for default-locale slugs.
     return {
       itemListElement: [
         ...splittedCategories.map((name, index) => {
@@ -198,4 +302,49 @@ export const StoreProduct: Record<string, GraphqlResolver<Root>> & {
   advertisement: ({ isVariantOf: { advertisement } }) => advertisement,
   deliveryPromiseBadges: ({ isVariantOf: { deliveryPromisesBadges } }) =>
     deliveryPromisesBadges,
+  otherLocales: async (root, _args, ctx) => {
+    if (!isLocalizationEnabled(ctx)) return null
+
+    const configuredLocales = getConfiguredLocales(ctx)
+
+    if (configuredLocales.length === 0) return null
+
+    const productId = root.isVariantOf.productId
+    const itemId = root.itemId
+    const locale = ctx.storage.locale
+    const defaultLocale = getDefaultLocale(ctx)
+
+    // availableLinkIds returns localized slug for every locale,
+    // we fetch for the current locale (reusing the request-scoped cache shared with the slug and
+    // breadcrumb resolvers) and read the full map from the response.
+    const entry = await getLocalizedProductEntry(ctx, productId, locale)
+
+    if (!entry?.availableLinkIds) return null
+
+    const { availableLinkIds } = entry
+    const { linkText } = root.isVariantOf
+
+    return configuredLocales
+      .map((configuredLocale) => {
+        // The default locale always uses the canonical IS linkText: it is always
+        // present and matches the Query.product `slug.startsWith(linkText)` fast
+        // path, so the fallback URL resolves cleanly even when the catalog has no
+        // default-locale entry in availableLinkIds.
+        if (configuredLocale === defaultLocale) {
+          return { locale: configuredLocale, slug: getSlug(linkText, itemId) }
+        }
+
+        // Non-default locales only appear when they have a registered localized slug
+        // in availableLinkIds. Untranslated locales are omitted so they are never
+        // advertised as hreflang alternates — this keeps the hreflang cluster
+        // symmetric across all locale variants of the product (every variant emits
+        // the same set: default + translated locales). The LocalizationSelector
+        // falls back to the default slug under the target prefix for omitted locales.
+        const linkId = availableLinkIds[configuredLocale]
+        return linkId
+          ? { locale: configuredLocale, slug: getSlug(linkId, itemId) }
+          : null
+      })
+      .filter((e): e is { locale: string; slug: string } => e !== null)
+  },
 }