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

package/dist/src/platforms/vtex/resolvers/query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../../../src/platforms/vtex/resolvers/query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,6BAA6B,EAC7B,uBAAuB,EACvB,oBAAoB,EACpB,2BAA2B,EAC3B,mBAAmB,EACnB,uBAAuB,EACvB,qBAAqB,EACrB,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,aAAa,EAEd,MAAM,+BAA+B,CAAA;AAWtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wCAAwC,CAAA;AAC1E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAA;AACvE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6CAA6C,CAAA;AACtF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAkC9C,eAAO,MAAM,KAAK;iBAEX,OAAO,eACG,gBAAgB,OACxB,cAAc;oBAgFhB,OAAO,YACA,mBAAmB,OACxB,cAAc;gBAShB,OAAO,6EAQP,eAAe,OACb,cAAc;;;;qBA4EhB,OAAO,gCACoB,oBAAoB,OAC7C,cAAc;;;;;;;;;;;;;kBAkChB,OAAO,kBACM,iBAAiB,OAC5B,cAAc;wBAwBhB,OAAO,gCACoB,uBAAuB,OAChD,cAAc;;;;;;;;;;;;;;;;;;uBAa6B,MAAM;;;;;kBA2CnD,OAAO,kCACsB,iBAAiB,OAC5C,cAAc;;;;;;;;;;;;;;;;;kBAkBhB,OAAO,4BACgB,iBAAiB,OACtC,cAAc;;;iBAqBhB,OAAO,yDAC6C,gBAAgB,OAClE,cAAc;;;;iBAqBhB,OAAO,UACF,gBAAgB,OACnB,cAAc;;;sBAyBhB,OAAO,YACA,qBAAqB,OAC1B,cAAc;mBAahB,OAAO,eACG,kBAAkB,OAC1B,cAAc;;;;;;;;;;;;;;;;;;;;;;;wBAqGhB,OAAO,WACD,uBAAuB,OAC3B,cAAc;;;;;;;;;;;;;;;wBAyBhB,OAAO,WACD;QACP,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;QACjB,aAAa,CAAC,EAAE,MAAM,CAAA;QACtB,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,aAAa,CAAC,EAAE,MAAM,CAAA;QACtB,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,KAAK,CAAC,EAAE,MAAM,CAAA;KACf,OACI,cAAc;;;;;;;;;;;;;;;;sBAoDG,OAAO,MAAM,OAAO,QAAQ,cAAc;;;8BAQ7D,OAAO,MACN,OAAO,OACN,cAAc;qBAWE,OAAO,MAAM,OAAO,OAAO,cAAc;;;;;;;;wBAqCtC,OAAO,MAAM,OAAO,OAAO,cAAc;;;;;4BAmD9D,OAAO,iBACK,2BAA2B,OACrC,cAAc,KAClB,OAAO,CAAC,aAAa,EAAE,CAAC;sBA4CtB,OAAO,sBACU,qBAAqB,OACpC,cAAc;;;;;;;oBAgBy1O,CAAC;;;;;;;;;;;;;;;;;;;;CADh3O,CAAA"}
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../../../src/platforms/vtex/resolvers/query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,6BAA6B,EAC7B,uBAAuB,EACvB,oBAAoB,EACpB,2BAA2B,EAC3B,mBAAmB,EACnB,uBAAuB,EACvB,qBAAqB,EACrB,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,aAAa,EAEd,MAAM,+BAA+B,CAAA;AAUtC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAA;AACvE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6CAA6C,CAAA;AACtF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAC9C,OAAO,KAAK,EACV,iBAAiB,EACjB,oBAAoB,EACrB,MAAM,uBAAuB,CAAA;AAU9B,OAAO,EAAc,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAA;AA4HlE,eAAO,MAAM,KAAK;iBAEX,OAAO,eACG,gBAAgB,OACxB,cAAc;oBAyChB,OAAO,YACA,mBAAmB,OACxB,cAAc;gBAgBhB,OAAO,6EAQP,eAAe,OACb,cAAc;;;;qBA4EhB,OAAO,gCACoB,oBAAoB,OAC7C,cAAc;;;;;;;;;;;;;kBAkChB,OAAO,kBACM,iBAAiB,OAC5B,cAAc;wBAwBhB,OAAO,gCACoB,uBAAuB,OAChD,cAAc;;;;;;;;;;;;;kBA8EhB,OAAO,kCACsB,iBAAiB,OAC5C,cAAc;;;;;;;;;;;;;;;;;kBAkBhB,OAAO,4BACgB,iBAAiB,OACtC,cAAc;;;iBAqBhB,OAAO,yDAC6C,gBAAgB,OAClE,cAAc;;;;iBAqBhB,OAAO,UACF,gBAAgB,OACnB,cAAc;;;sBAyBhB,OAAO,YACA,qBAAqB,OAC1B,cAAc;mBAahB,OAAO,eACG,kBAAkB,OAC1B,cAAc;;;;;;;;;;;;;;;;;;;;;;;wBAqGhB,OAAO,WACD,uBAAuB,OAC3B,cAAc;;;;;;;;;;;;;;;wBAyBhB,OAAO,WACD;QACP,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;QACjB,aAAa,CAAC,EAAE,MAAM,CAAA;QACtB,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,aAAa,CAAC,EAAE,MAAM,CAAA;QACtB,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,KAAK,CAAC,EAAE,MAAM,CAAA;KACf,OACI,cAAc;;;;;;;;;;;;;;;;sBAoDG,OAAO,MAAM,OAAO,QAAQ,cAAc;;;8BAQ7D,OAAO,MACN,OAAO,OACN,cAAc;qBAWE,OAAO,MAAM,OAAO,OAAO,cAAc;;;;;;;;wBAqCtC,OAAO,MAAM,OAAO,OAAO,cAAc;;;;;4BAmD9D,OAAO,iBACK,2BAA2B,OACrC,cAAc,KAClB,OAAO,CAAC,aAAa,EAAE,CAAC;sBA4CtB,OAAO,sBACU,qBAAqB,OACpC,cAAc;;;;;;;oBAgB01N,CAAC;;;;;;;;;;;;;;;;;;;;CADj3N,CAAA"}

package/dist/src/platforms/vtex/resolvers/validateCart.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validateCart.d.ts","sourceRoot":"","sources":["../../../../../src/platforms/vtex/resolvers/validateCart.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,IAAI,CAAA;AACxC,OAAO,KAAK,EAMV,wBAAwB,EACzB,MAAM,+BAA+B,CAAA;AA0TtC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,YAAY,GACvB,GAAG,OAAO,EACV,8BAA8B,wBAAwB,EACtD,KAAK,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SAkMpB,CAAA"}
+{"version":3,"file":"validateCart.d.ts","sourceRoot":"","sources":["../../../../../src/platforms/vtex/resolvers/validateCart.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,IAAI,CAAA;AACxC,OAAO,KAAK,EAMV,wBAAwB,EACzB,MAAM,+BAA+B,CAAA;AA+TtC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,YAAY,GACvB,GAAG,OAAO,EACV,8BAA8B,wBAAwB,EACtD,KAAK,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SAkMpB,CAAA"}

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

@@ -0,0 +1,28 @@
+import { GraphqlContext } from '..';
+export interface LocalizationConfig {
+    enabled?: boolean;
+    defaultLocale?: string;
+    locales?: Record<string, unknown>;
+}
+export declare const getLocalizationConfig: (ctx: GraphqlContext) => LocalizationConfig;
+export declare const isLocalizationEnabled: (ctx: GraphqlContext) => boolean;
+export declare const getConfiguredLocales: (ctx: GraphqlContext) => string[];
+export declare const getDefaultLocale: (ctx: GraphqlContext) => string | undefined;
+/**
+ * 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 declare const isConfiguredLocale: (ctx: GraphqlContext, locale: string) => boolean;
+/**
+ * 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 declare const getCatalogLocale: (ctx: GraphqlContext) => string | undefined;
+//# sourceMappingURL=localization.d.ts.map

package/dist/src/platforms/vtex/utils/localization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"localization.d.ts","sourceRoot":"","sources":["../../../../../src/platforms/vtex/utils/localization.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,IAAI,CAAA;AAExC,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClC;AAED,eAAO,MAAM,qBAAqB,GAChC,KAAK,cAAc,KAClB,kBAEqB,CAAA;AAExB,eAAO,MAAM,qBAAqB,GAAI,KAAK,cAAc,KAAG,OACf,CAAA;AAE7C,eAAO,MAAM,oBAAoB,GAAI,KAAK,cAAc,KAAG,MAAM,EACV,CAAA;AAEvD,eAAO,MAAM,gBAAgB,GAAI,KAAK,cAAc,KAAG,MAAM,GAAG,SACtB,CAAA;AAE1C;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAC7B,KAAK,cAAc,EACnB,QAAQ,MAAM,KACb,OAAqD,CAAA;AAExD;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,GAAI,KAAK,cAAc,KAAG,MAAM,GAAG,SACU,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faststore/api",
-  "version": "4.5.0-dev.3",
+  "version": "4.5.0-dev.5",
   "license": "MIT",
   "main": "dist/cjs/index.js",
   "typings": "dist/src/index.d.ts",
@@ -58,11 +58,11 @@
     "vite": "7.1.5",
     "vite-plugin-dts": "4.5.4",
     "vitest": "^4.0.7",
-    "@faststore/diagnostics": "^4.5.0-dev.3"
+    "@faststore/diagnostics": "^4.5.0-dev.5"
   },
   "peerDependencies": {
     "graphql": "16.11.0",
-    "@faststore/diagnostics": "4.5.0-dev.3"
+    "@faststore/diagnostics": "4.5.0-dev.5"
   },
   "publishConfig": {
     "access": "public"

package/src/__generated__/schema.ts

@@ -510,6 +510,8 @@ export type IStoreOffer = {
   listPrice: Scalars['Float']['input'];
   /** Also known as spot price. */
   price: Scalars['Float']['input'];
+  /** Signed price token (JWT) from the Pricing Fallback feature, forwarded to Checkout on add-to-cart. */
+  priceToken?: InputMaybe<Scalars['String']['input']>;
   /** Number of items offered. */
   quantity: Scalars['Int']['input'];
   /** Seller responsible for the offer. */
@@ -1347,6 +1349,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 +1389,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 +1405,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'
 };
 
@@ -1560,6 +1591,12 @@ export type StoreOffer = {
   price: Scalars['Float']['output'];
   /** ISO code of the currency used for the offer prices. */
   priceCurrency: Scalars['String']['output'];
+  /**
+   * Signed price token (JWT) used by the Pricing Fallback feature. When present, it should be
+   * forwarded to Checkout on add-to-cart so the platform can trust the offer's price even if
+   * the Pricing System is unavailable. May be null when the signing step fails or the feature is disabled.
+   */
+  priceToken?: Maybe<Scalars['String']['output']>;
   /** Next date in which price is scheduled to change. If there is no scheduled change, this will be set a year in the future from current time. */
   priceValidUntil: Scalars['String']['output'];
   /** Also known as spot price with taxes. */
@@ -1688,6 +1725,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 +1794,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/commerce/types/OrderForm.ts

@@ -4,6 +4,11 @@ export interface OrderFormInputItem {
   seller: string
   index?: number
   attachments?: Attachment[]
+  /**
+   * Signed price token (JWT) from the Pricing Fallback feature. Forwarded to Checkout so it can
+   * trust the offer's price even if the Pricing System is down. Omitted when not available.
+   */
+  priceToken?: string
 }
 
 export interface Attachment {

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/clients/search/types/ProductSearchResult.ts

@@ -175,6 +175,13 @@ export interface CommertialOffer {
   }>
   GetInfoErrorMessage: any | null
   CacheVersionUsedToCallCheckout: string
+  /**
+   * Signed price (JWT) used by the Pricing Fallback feature. When present, it is
+   * forwarded to Checkout on add-to-cart so the platform can trust the offer's
+   * price even if the Pricing System is unavailable. It may be absent when the
+   * signing step fails or the feature is disabled.
+   */
+  PriceToken?: string
 }
 
 export interface Seller {

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 ?? ''}`,
   })
 }