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

package/src/__generated__/schema.ts

@@ -1347,6 +1347,11 @@ export type StoreCollection = {
   id: Scalars['ID']['output'];
   /** Collection meta information. Used for search. */
   meta: StoreCollectionMeta;
+  /**
+   * Localized versions of this collection for all available locales.
+   * Only populated when localization is enabled.
+   */
+  otherLocales?: Maybe<Array<StoreCollectionLocale>>;
   /** Meta tag data. */
   seo: StoreSeo;
   /** Corresponding collection URL slug, with which to retrieve this entity. */
@@ -1382,6 +1387,15 @@ export type StoreCollectionFacet = {
   value: Scalars['String']['output'];
 };
 
+/** Localized collection data for a specific locale. */
+export type StoreCollectionLocale = {
+  __typename?: 'StoreCollectionLocale';
+  /** Locale code (e.g. "pt-BR", "it-IT"). */
+  locale: Scalars['String']['output'];
+  /** Localized collection slug (e.g. "vestuario/camisetas"). */
+  slug: Scalars['String']['output'];
+};
+
 /** Collection meta information. Used for search. */
 export type StoreCollectionMeta = {
   __typename?: 'StoreCollectionMeta';
@@ -1389,19 +1403,34 @@ export type StoreCollectionMeta = {
   selectedFacets: Array<StoreCollectionFacet>;
 };
 
-/** 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.
+ */
 export const enum StoreCollectionType {
   /** Product brand. */
   Brand = 'Brand',
   /** Second level of product categorization. */
   Category = 'Category',
-  /** Product cluster. */
+  /**
+   * Product cluster.
+   *
+   * Deprecated: never returned — clusters resolve as `Collection`.
+   * @deprecated 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.
+   */
   Cluster = 'Cluster',
   /** Product collection. */
   Collection = 'Collection',
   /** First level of product categorization. */
   Department = 'Department',
-  /** Third level of product categorization. */
+  /**
+   * Third level of product categorization.
+   *
+   * Deprecated: never returned — third-level categories resolve as `Category`.
+   * @deprecated 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.
+   */
   SubCategory = 'SubCategory'
 };
 
@@ -1688,6 +1717,11 @@ export type StoreProduct = {
   name: Scalars['String']['output'];
   /** Aggregate offer information. */
   offers: StoreAggregateOffer;
+  /**
+   * Localized versions of this product for all available locales.
+   * Only populated when localization is enabled.
+   */
+  otherLocales?: Maybe<Array<StoreProductLocale>>;
   /** Product ID, such as [ISBN](https://www.isbn-international.org/content/what-isbn) or similar global IDs. */
   productID: Scalars['String']['output'];
   /** The product's release date. Formatted using https://en.wikipedia.org/wiki/ISO_8601 */
@@ -1752,6 +1786,15 @@ export type StoreProductGroup = {
   skuVariants?: Maybe<SkuVariants>;
 };
 
+/** Localized product data for a specific locale. */
+export type StoreProductLocale = {
+  __typename?: 'StoreProductLocale';
+  /** Locale code (e.g. "pt-BR", "it-IT"). */
+  locale: Scalars['String']['output'];
+  /** Localized product slug including the SKU ID suffix (e.g. "adidas-polo-uomo-65"). */
+  slug: Scalars['String']['output'];
+};
+
 /** Properties that can be associated with products and products groups. */
 export type StorePropertyValue = {
   __typename?: 'StorePropertyValue';

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

@@ -0,0 +1,52 @@
+import { fetchAPI } from '../fetch'
+
+export interface LocalizedCategoryEntry {
+  id: number
+  name: string
+  /** Slash-separated IDs from root to this node, e.g. "9281/9285". Used to determine depth. */
+  fullPath: string
+  /** Slash-separated localized slugs from root to this node, e.g. "apparel/t-shirts". */
+  fullPathUriName: string
+}
+
+export interface LocalizedProductEntry {
+  linkId: string
+  /** All categories the product belongs to across all trees, as returned by Catalog Dataplane. */
+  categories: LocalizedCategoryEntry[]
+  /** Localized linkIds keyed by locale, covering all available locales in a single response. */
+  availableLinkIds: Record<string, string>
+}
+
+export interface LocalizedProductResponse {
+  id: number
+  linkId: string
+  name: string
+  /** Leaf category (deepest level) the product is registered under. */
+  category: LocalizedCategoryEntry | null
+  /** Full ancestry chain for every category tree the product belongs to. */
+  categories: LocalizedCategoryEntry[]
+  /** Localized linkIds keyed by locale, covering all available locales in a single response. */
+  availableLinkIds: Record<string, string>
+}
+
+/**
+ * Client for the VTEX Catalog Dataplane API.
+ * Uses Accept-Language header to return locale-specific product data.
+ */
+export const CatalogDataplane = ({ account, environment }: Options) => {
+  const base = `https://${account}.${environment}.com.br`
+
+  return {
+    getLocalizedProduct: (
+      productId: string,
+      locale: string
+    ): Promise<LocalizedProductResponse> =>
+      fetchAPI(`${base}/api/catalog-dataplane/product/${productId}`, {
+        method: 'GET',
+        headers: {
+          'Accept-Language': locale,
+          'Content-Type': 'application/json',
+        },
+      }),
+  }
+}

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

@@ -14,6 +14,7 @@ import {
   type UserOrderCancel,
   type UserOrderListResult,
 } from '../../../..'
+import { isNotFoundError } from '../../../errors'
 import type { GraphqlContext } from '../../index'
 import { getWithAppKeyAndToken } from '../../utils/auth'
 import type { Channel } from '../../utils/channel'
@@ -26,6 +27,11 @@ import {
 import type { ContractResponse } from './Contract'
 import type { Address, AddressInput } from './types/Address'
 import type { Brand } from './types/Brand'
+import type {
+  ByLinkIdBrandResponse,
+  ByLinkIdCategoryResponse,
+  ByLinkIdCollectionResponse,
+} from './types/ByLinkId'
 import type { CategoryTree } from './types/CategoryTree'
 import type { MasterDataResponse } from './types/Newsletter'
 import type {
@@ -74,6 +80,24 @@ const BASE_INIT = {
   },
 }
 
+/**
+ * Encode a by-linkid path for the category endpoint. Category link paths can be
+ * multi-segment (e.g. "computer---software/eletronicos"); the Catalog endpoint
+ * expects the "/" separators to stay literal so it can validate each level,
+ * while each segment is individually URL-encoded. Running encodeURIComponent on
+ * the whole string would turn "/" into "%2F" and break multi-segment resolution.
+ */
+const encodeLinkIdPath = (linkId: string): string =>
+  linkId.split('/').map(encodeURIComponent).join('/')
+
+/**
+ * Build the fetch init that forwards a locale to a by-linkid endpoint. When no
+ * locale is provided the endpoint falls back to the store's default registered
+ * language (non-localized stores behavior).
+ */
+const byLinkIdInit = (locale?: string): RequestInit | undefined =>
+  locale ? { headers: { 'Accept-Language': locale } } : undefined
+
 const QUOTE_ISO_DATE = /^\d{4}-\d{2}-\d{2}$/
 const QUOTE_VALID_STATUSES = new Set([
   'Draft',
@@ -222,6 +246,53 @@ export const VtexCommerce = (
             { storeCookies }
           ),
       },
+      byLinkId: {
+        // The by-linkid endpoints resolve a slug to a single catalog entity
+        // (or 404 when there is no match). We surface a 404 as `null` so the
+        // loader can cascade category → brand → collection.
+        category: async (
+          linkId: string,
+          locale?: string
+        ): Promise<ByLinkIdCategoryResponse | null> => {
+          try {
+            return await fetchAPI(
+              `${base}/api/catalog_system/pub/category/by-linkid/${encodeLinkIdPath(linkId)}`,
+              byLinkIdInit(locale)
+            )
+          } catch (error) {
+            if (isNotFoundError(error)) return null
+            throw error
+          }
+        },
+        brand: async (
+          linkId: string,
+          locale?: string
+        ): Promise<ByLinkIdBrandResponse | null> => {
+          try {
+            return await fetchAPI(
+              `${base}/api/catalog_system/pub/brand/by-linkid/${encodeURIComponent(linkId)}`,
+              byLinkIdInit(locale)
+            )
+          } catch (error) {
+            if (isNotFoundError(error)) return null
+            throw error
+          }
+        },
+        collection: async (
+          linkId: string,
+          locale?: string
+        ): Promise<ByLinkIdCollectionResponse | null> => {
+          try {
+            return await fetchAPI(
+              `${base}/api/catalog_system/pub/collection/by-linkid/${encodeURIComponent(linkId)}`,
+              byLinkIdInit(locale)
+            )
+          } catch (error) {
+            if (isNotFoundError(error)) return null
+            throw error
+          }
+        },
+      },
       products: {
         crossselling: ({
           type,

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

@@ -0,0 +1,46 @@
+export interface ByLinkIdCategoryResponse {
+  id: number
+  fatherCategoryId: number | null
+  name: string
+  linkId: string
+  title: string | null
+  description: string | null
+  /**
+   * Optional SEO meta description. pagetype.metaTagDescription
+   * was backed by the same source as `description`; prefer `description` for
+   * parity when this field is absent.
+   */
+  metaTagDescription: string | null
+  /** Localized linkIds keyed by locale. Null when no multilanguage entries are registered. */
+  availableLinkIds: Record<string, string> | null
+}
+
+export interface ByLinkIdBrandResponse {
+  id: number
+  name: string
+  linkId: string
+  title: string | null
+  description: string | null
+  /**
+   * Optional SEO meta description. Catalog confirmed pagetype.metaTagDescription
+   * was backed by the same source as `description`; prefer `description` for
+   * parity when this field is absent.
+   */
+  metaTagDescription: string | null
+  availableLinkIds: Record<string, string> | null
+}
+
+export interface ByLinkIdCollectionResponse {
+  id: number
+  name: string
+  linkId: string | null
+  title: string | null
+  description: string | null
+  /**
+   * Optional SEO meta description. pagetype.metaTagDescription
+   * was backed by the same source as `description`; prefer `description` for
+   * parity when this field is absent.
+   */
+  metaTagDescription: string | null
+  availableLinkIds: Record<string, string> | null
+}

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

@@ -1,4 +1,5 @@
 import type { GraphqlContext } from '..'
+import { CatalogDataplane } from './catalog'
 import { VtexCommerce } from './commerce'
 import { IntelligentSearch } from './search'
 
@@ -7,9 +8,11 @@ export type Clients = ReturnType<typeof getClients>
 export const getClients = (options: Options, ctx: GraphqlContext) => {
   const search = IntelligentSearch(options, ctx)
   const commerce = VtexCommerce(options, ctx)
+  const catalog = CatalogDataplane(options)
 
   return {
     search,
     commerce,
+    catalog,
   }
 }

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

@@ -3,6 +3,7 @@ import pLimit from 'p-limit'
 import type { GraphqlContext } from '../../'
 import { getWithCookie } from '../../utils/cookies'
 import type { SelectedFacet } from '../../utils/facets'
+import { isLocalizationEnabled } from '../../utils/localization'
 import {
   buildIntelligentSearchRequest,
   parseSegmentCookie,
@@ -80,10 +81,21 @@ function getRegionIdFromContext(ctx: GraphqlContext): string | undefined {
 
 function getSegmentLocale(ctx: GraphqlContext): string {
   const segment = parseSegmentCookie(ctx.headers?.cookie)
-
-  // Prefer ctx.storage.locale (set from trusted selectedFacets) over the
-  // vtex_segment cookie, which can lag on hard locale-switch navigation.
-  return ctx.storage.locale || (segment.cultureInfo as string | undefined) || ''
+  const cultureInfo = (segment.cultureInfo as string | undefined) || ''
+
+  // Locale flows from the URL into IS in one chain:
+  //   router.locale (Next.js)
+  //     → selectedFacets locale facet (useLocalizedVariables in @faststore/core)
+  //     → ctx.storage.locale (mutateLocaleContext in query.ts)
+  //     → IS locale query param (here)
+  //
+  // For localized stores: prefer storage.locale over the vtex_segment cookie.
+  // The cookie can lag after locale navigation, while storage.locale is derived
+  // from the trusted selectedFacets locale facet in the same request.
+
+  return isLocalizationEnabled(ctx)
+    ? ctx.storage.locale || cultureInfo
+    : cultureInfo || ctx.storage.locale || ''
 }
 
 export const IntelligentSearch = (

package/src/platforms/vtex/index.ts

@@ -32,10 +32,22 @@ export interface GraphqlContext {
     flags: FeatureFlags
     searchArgs?: Omit<SearchArgs, 'type'>
     cookies: Map<string, Record<string, string>>
+    /**
+     * Cached in-flight localized product lookups keyed by "productId:locale".
+     * Stores the promise (not just the resolved value) so concurrent sibling
+     * resolvers (slug validation, otherLocales, breadcrumb) dedupe to a single
+     * Catalog Dataplane request within the same request.
+     */
+    productTranslationsCache?: Map<
+      string,
+      Promise<import('./clients/catalog').LocalizedProductEntry | null>
+    >
   }
   headers: Record<string, string>
   account: string
   OTEL: Record<string, unknown>
+  /** Discovery config passed from @faststore/core, including localization settings. */
+  discoveryConfig?: Record<string, unknown>
 }
 
 export const GraphqlVtexContextFactory = async (options: Options) => {
@@ -49,11 +61,14 @@ export const GraphqlVtexContextFactory = async (options: Options) => {
           locale: options.locale,
           cookies: new Map<string, Record<string, string>>(),
         }
-        ctx.clients = getClients(options, ctx)
-        ctx.loaders = getLoaders(options, ctx)
         ctx.account = options.account
         ctx.OTEL = options.OTEL
         ctx.discoveryConfig = options.discoveryConfig
+        // Build clients/loaders last: they capture `ctx` and read storage,
+        // discoveryConfig, etc. at request time, so everything they may depend on
+        // must already be assigned.
+        ctx.clients = getClients(options, ctx)
+        ctx.loaders = getLoaders(options, ctx)
 
         return ctx
       }

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

@@ -3,49 +3,123 @@ import pLimit from 'p-limit'
 
 import { NotFoundError } from '../../errors'
 import type { Clients } from '../clients'
-import type { CollectionPageType } from '../clients/commerce/types/Portal'
+import type {
+  ByLinkIdBrandResponse,
+  ByLinkIdCategoryResponse,
+  ByLinkIdCollectionResponse,
+} from '../clients/commerce/types/ByLinkId'
 
-// Limits concurrent requests to 20 so that they don't timeout
 const CONCURRENT_REQUESTS_MAX = 20
 
-const collectionPageTypes = new Set([
-  'brand',
-  'category',
-  'department',
-  'subcategory',
-  'collection',
-  'cluster',
-] as const)
+/**
+ * Load key for the collection DataLoader. `locale` is captured at the call
+ * site (not re-read from mutable `ctx.storage`) so concurrent aliased
+ * `collection` fields with different locales cannot share a cache entry or
+ * race on Accept-Language.
+ */
+export type CollectionLoadKey = {
+  slug: string
+  /** Catalog Accept-Language; `undefined` when localization is disabled. */
+  locale?: string
+}
+
+export type ByLinkIdCategoryRoot = ByLinkIdCategoryResponse & {
+  entityType: 'category'
+  /**
+   * Full accumulated input slug injected by the loader (e.g. "vestuario/camisetas").
+   * Used by slugifyRoot so that meta.selectedFacets builds the correct facet keys
+   * without relying on root.url (which is absent in the by-linkid response).
+   */
+  slug: string
+}
+
+export type ByLinkIdBrandRoot = ByLinkIdBrandResponse & {
+  entityType: 'brand'
+}
+
+export type ByLinkIdCollectionRoot = ByLinkIdCollectionResponse & {
+  entityType: 'collection'
+}
+
+export type Root =
+  | ByLinkIdCategoryRoot
+  | ByLinkIdBrandRoot
+  | ByLinkIdCollectionRoot
+
+export const isCategory = (root: Root): root is ByLinkIdCategoryRoot =>
+  root.entityType === 'category'
 
-export const isCollectionPageType = (x: any): x is CollectionPageType =>
-  typeof x.pageType === 'string' &&
-  collectionPageTypes.has(x.pageType.toLowerCase())
+export const isBrand = (root: Root): root is ByLinkIdBrandRoot =>
+  root.entityType === 'brand'
+
+export const isCollection = (root: Root): root is ByLinkIdCollectionRoot =>
+  root.entityType === 'collection'
 
 export const getCollectionLoader = (_: Options, clients: Clients) => {
   const limit = pLimit(CONCURRENT_REQUESTS_MAX)
 
-  const loader = async (
-    slugs: readonly string[]
-  ): Promise<CollectionPageType[]> => {
-    return Promise.all(
-      slugs.map((slug: string) =>
+  const loader = async (keys: readonly CollectionLoadKey[]): Promise<Root[]> =>
+    Promise.all(
+      keys.map((key) =>
         limit(async () => {
-          const page = await clients.commerce.catalog.portal.pagetype(slug)
+          // Normalize to lowercase for DataLoader cache-key consistency
+          // (e.g. "Sporting" and "sporting" are the same). The by-linkid API is
+          // case-insensitive by design (it preserves the legacy pagetype behavior).
+          // Accents are significant and are preserved by toLowerCase() (e.g. "vestuário").
+          const normalizedSlug = key.slug.toLowerCase()
+          // Use the locale captured on the load key — do not re-read
+          // ctx.storage.locale here (it can change mid-request).
+          const locale = key.locale
+
+          // Step 1: category
+          // Pass the full path so the API validates each segment and returns only
+          // the unambiguous leaf category. E.g. "vestuario/camisetas" resolves to
+          // the "camisetas" that is a child of "vestuario", not any other category
+          // that happens to share the linkId "camisetas".
+          // The full slug is also injected into the result for meta.selectedFacets
+          // and breadcrumb URL construction.
+          const category = await clients.commerce.catalog.byLinkId.category(
+            normalizedSlug,
+            locale
+          )
+          if (category) {
+            return {
+              ...category,
+              entityType: 'category' as const,
+              slug: normalizedSlug,
+            }
+          }
 
-          if (isCollectionPageType(page)) {
-            return page
+          // Step 2: brand (always single-segment)
+          const brand = await clients.commerce.catalog.byLinkId.brand(
+            normalizedSlug,
+            locale
+          )
+          if (brand) {
+            return { ...brand, entityType: 'brand' as const }
+          }
+
+          // Step 3: collection cluster (always single-segment)
+          const collection = await clients.commerce.catalog.byLinkId.collection(
+            normalizedSlug,
+            locale
+          )
+          if (collection) {
+            return { ...collection, entityType: 'collection' as const }
           }
 
           throw new NotFoundError(
-            `Catalog returned ${page.pageType} for slug: ${slug}. This usually happens when there is more than one category with the same name in the same category tree level.`
+            `No catalog entity found for slug: ${key.slug}. Cascade exhausted (category → brand → collection).`
           )
         })
       )
     )
-  }
 
-  return new DataLoader<string, CollectionPageType>(loader, {
-    // DataLoader is being used to cache requests, not to batch them
+  return new DataLoader<CollectionLoadKey, Root, string>(loader, {
+    // DataLoader is used for caching, not batching
     batch: false,
+    // Dedup by lowercased slug + captured locale so casing variants share an
+    // entry while same-slug / different-locale loads stay isolated.
+    cacheKeyFn: ({ slug, locale }) => `${slug.toLowerCase()}::${locale ?? ''}`,
   })
 }

package/src/platforms/vtex/loaders/index.ts

@@ -6,7 +6,8 @@ import { getSkuLoader } from './sku'
 
 export type Loaders = ReturnType<typeof getLoaders>
 
-export const getLoaders = (options: Options, { clients }: GraphqlContext) => {
+export const getLoaders = (options: Options, ctx: GraphqlContext) => {
+  const { clients } = ctx
   const skuLoader = getSkuLoader(options, clients)
   const simulationLoader = getSimulationLoader(options, clients)
   const collectionLoader = getCollectionLoader(options, clients)