feat: replace pagetype with by-linkid cascade + localized PLP/collection pages

packages/api/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 {
@@ -107,6 +113,44 @@ export const VtexCommerce = (
             { storeCookies }
           ),
       },
+      byLinkId: {
+        category: async (
+          linkId: string
+        ): Promise<ByLinkIdCategoryResponse[] | null> => {
+          try {
+            return await fetchAPI(
+              `${base}/api/catalog_system/pub/category/by-linkid/${encodeURIComponent(linkId)}`
+            )
+          } catch (error) {
+            if (isNotFoundError(error)) return null
+            throw error
+          }
+        },
+        brand: async (
+          linkId: string
+        ): Promise<ByLinkIdBrandResponse[] | null> => {
+          try {
+            return await fetchAPI(
+              `${base}/api/catalog_system/pub/brand/by-linkid/${encodeURIComponent(linkId)}`
+            )
+          } catch (error) {
+            if (isNotFoundError(error)) return null
+            throw error
+          }
+        },
+        collection: async (
+          linkId: string
+        ): Promise<ByLinkIdCollectionResponse[] | null> => {
+          try {
+            return await fetchAPI(
+              `${base}/api/catalog_system/pub/collection/by-linkid/${encodeURIComponent(linkId)}`
+            )
+          } catch (error) {
+            if (isNotFoundError(error)) return null
+            throw error
+          }
+        },
+      },
       products: {
         crossselling: ({
           type,

packages/api/src/platforms/vtex/clients/commerce/types/ByLinkId.ts

@@ -0,0 +1,34 @@
+export interface ByLinkIdCategoryResponse {
+  id: number
+  fatherCategoryId: number | null
+  name: string
+  linkId: string
+  title: string | null
+  description: string | null
+  /** SEO meta description — equivalent to pagetype.metaTagDescription. TODO: to be added by Catalog team. */
+  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
+  /** SEO meta description — equivalent to pagetype.metaTagDescription. TODO: to be added by Catalog team. */
+  metaTagDescription: string | null
+  availableLinkIds: Record<string, string> | null
+}
+
+export interface ByLinkIdCollectionResponse {
+  id: number
+  name: string
+  linkId: string | null
+  title: string | null
+  description: string | null
+  /** SEO meta description — equivalent to pagetype.metaTagDescription. TODO: to be added by Catalog team. */
+  metaTagDescription: string | null
+  availableLinkIds: Record<string, string> | null
+}

packages/api/src/platforms/vtex/clients/search/index.ts

@@ -80,10 +80,25 @@ 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.
+
+  const isLocalizationEnabled =
+    (ctx.discoveryConfig as { localization?: { enabled?: boolean } })
+      ?.localization?.enabled === true
+
+  return isLocalizationEnabled
+    ? ctx.storage.locale || cultureInfo
+    : cultureInfo || ctx.storage.locale || ''
 }
 
 export const IntelligentSearch = (

packages/api/src/platforms/vtex/index.ts

@@ -37,6 +37,10 @@ export interface GraphqlContext {
       string,
       import('./clients/catalog').LocalizedProductEntry
     >
+    /** Request-scoped cache for the full category tree (depth 10). Shared between meta and otherLocales resolvers. */
+    categoryTree?: import(
+      './clients/commerce/types/CategoryTree'
+    ).CategoryTree[]
   }
   headers: Record<string, string>
   account: string

packages/api/src/platforms/vtex/loaders/collection.ts

@@ -3,49 +3,103 @@ 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)
+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[]> => {
+  const loader = async (slugs: readonly string[]): Promise<Root[]> => {
     return Promise.all(
       slugs.map((slug: string) =>
         limit(async () => {
-          const page = await clients.commerce.catalog.portal.pagetype(slug)
+          // Normalize to lowercase so that merchants who register linkIds with mixed
+          // casing (allowed by the Catalog multilanguage API) get the same resolution
+          // as lowercase URLs. The by-linkid API is case-sensitive, while the legacy
+          // pagetype API was not, so skipping this would be a regression.
+          const normalizedSlug = slug.toLowerCase()
+
+          // For multi-segment slugs (e.g. "vestuario/camisetas") the entity type is
+          // determined by the last segment — the leaf category owns the page.
+          // The full slug is injected into the result for meta.selectedFacets and
+          // breadcrumb URL construction.
+          const lastSegment = normalizedSlug.split('/').at(-1)!
+
+          // Step 1: category
+          const categories =
+            await clients.commerce.catalog.byLinkId.category(lastSegment)
+          if (categories !== null && categories.length > 0) {
+            // When multiple categories share the same linkId at different tree levels
+            // (e.g. "bolas" under both "esportes" and "infantil"), fatherCategoryId-based
+            // disambiguation can be added here in a follow-up. For now, take the first match.
+            return {
+              ...categories[0],
+              entityType: 'category' as const,
+              slug: normalizedSlug,
+            }
+          }
+
+          // Step 2: brand (always single-segment)
+          const brands =
+            await clients.commerce.catalog.byLinkId.brand(normalizedSlug)
+          if (brands !== null && brands.length > 0) {
+            return { ...brands[0], entityType: 'brand' as const }
+          }
 
-          if (isCollectionPageType(page)) {
-            return page
+          // Step 3: collection cluster (always single-segment)
+          const collections =
+            await clients.commerce.catalog.byLinkId.collection(normalizedSlug)
+          if (collections !== null && collections.length > 0) {
+            return { ...collections[0], 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: ${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<string, Root>(loader, {
+    // DataLoader is used for caching, not batching
     batch: false,
   })
 }