feat(core): add RecommendationShelf section with personalization tracking

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

@@ -45,12 +45,28 @@ import type {
   SimulationArgs,
   SimulationOptions,
 } from './types/Simulation'
+import type {
+  RecommendationResult,
+  StartRecommendationSessionResult,
+} from './types/RecommendationResult'
 import type { ScopesByUnit, UnitResponse } from './types/Unit'
 import type { VtexIdResponse } from './types/VtexId'
 import type { QuoteListResult, ListUserQuotesArgs } from './types/Quote'
 
 type ValueOf<T> = T extends Record<string, infer K> ? K : never
 
+// Identifies the storefront origin to the Recommendations BFF, as required by
+// the API (`x-vtex-rec-origin` header).
+const REC_ORIGIN_SUFFIX = 'storefront/faststore.recommendation-shelf@v4'
+
+export interface RecommendationArgs {
+  campaignVrn: string
+  userId?: string
+  products?: string[]
+  salesChannel?: string
+  locale?: string
+}
+
 const BASE_INIT = {
   method: 'POST',
   headers: {
@@ -156,6 +172,14 @@ export const VtexCommerce = (
 
   const forwardedHost = host.replace(selectedPrefix, '')
 
+  // Recommendations BFF (`/api/recommend-bff/v2`) lives under the same account
+  // host as the other commerce APIs, so it's exposed here as a namespace.
+  const recommendationBase = `${base}/api/recommend-bff/v2`
+  const recommendationHeaders: HeadersInit = withCookie({
+    accept: 'application/json',
+    'content-type': 'application/json',
+    'x-vtex-rec-origin': `${account}/${REC_ORIGIN_SUFFIX}`,
+  })
   const withBuyerAuthHeaders = (
     additionalHeaders: Record<string, string> = {}
   ): HeadersInit => {
@@ -1096,5 +1120,55 @@ export const VtexCommerce = (
         )
       },
     },
+
+    // Anonymous personalization / recommendations served by the VTEX
+    // Recommendations BFF. The BFF replies with `vtex-rec-*` Set-Cookie headers
+    // (forwarded to the browser via `ctx.storage.cookies`) and returns products
+    // already hydrated in the Intelligent Search shape.
+    recommendation: {
+      recommendations: ({
+        campaignVrn,
+        userId,
+        products = [],
+        salesChannel,
+        locale,
+      }: RecommendationArgs): Promise<RecommendationResult> => {
+        const params = new URLSearchParams({ an: account, campaignVrn })
+
+        if (userId) {
+          params.append('userId', userId)
+        }
+
+        if (products.length > 0) {
+          params.append('products', products.join(','))
+        }
+
+        if (salesChannel) {
+          params.append('salesChannel', salesChannel)
+        }
+
+        if (locale) {
+          params.append('locale', locale)
+        }
+
+        return fetchAPI(
+          `${recommendationBase}/recommendations?${params.toString()}`,
+          { headers: recommendationHeaders },
+          { storeCookies }
+        )
+      },
+
+      startRecommendationSession: (): Promise<
+        StartRecommendationSessionResult | undefined
+      > => {
+        const params = new URLSearchParams({ an: account })
+
+        return fetchAPI(
+          `${recommendationBase}/users/start-session?${params.toString()}`,
+          { method: 'POST', headers: recommendationHeaders },
+          { storeCookies }
+        )
+      },
+    },
   }
 }

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

@@ -0,0 +1,27 @@
+import type { Product } from '../../search/types/ProductSearchResult'
+
+/**
+ * Raw response of the VTEX Recommendations BFF
+ * (`GET /api/recommend-bff/v2/recommendations`).
+ *
+ * The BFF already returns the products fully hydrated in the same Intelligent
+ * Search shape (`Product`) used by the `search` query, so the resolver can map
+ * them straight to the normalized `StoreProduct` shape via `pickBestSku` +
+ * `enhanceSku` — no extra round-trip to search is needed.
+ */
+export interface RecommendationResult {
+  products: Product[]
+  correlationId: string
+  campaign: RecommendationBffCampaign
+}
+
+export interface RecommendationBffCampaign {
+  id: string
+  title?: string
+  type: string
+}
+
+/** Response of `POST /api/recommend-bff/v2/users/start-session`. */
+export interface StartRecommendationSessionResult {
+  recommendationsUserId: string
+}

packages/api/src/platforms/vtex/resolvers/mutation.ts

@@ -1,6 +1,7 @@
 import { cancelOrder } from './cancelOrder'
 import { processOrderAuthorization } from './processOrderAuthorization'
 import { startOrderEntryOperation } from './startOrderEntryOperation'
+import { startRecommendationSession } from './startRecommendationSession'
 import { subscribeToNewsletter } from './subscribeToNewsletter'
 import { uploadFileToOrderEntry } from './uploadFileToOrderEntry'
 import { validateCart } from './validateCart'
@@ -14,4 +15,5 @@ export const Mutation = {
   processOrderAuthorization,
   uploadFileToOrderEntry,
   startOrderEntryOperation,
+  startRecommendationSession,
 }

packages/api/src/platforms/vtex/resolvers/query.ts

@@ -20,6 +20,7 @@ import type {
 } from '../../../__generated__/schema'
 import { getOrderEntryOperation } from './getOrderEntryOperation'
 import { getOrderFormItems } from './getOrderFormItems'
+import { recommendations } from './recommendations'
 import {
   BadRequestError,
   ForbiddenError,
@@ -838,4 +839,5 @@ export const Query = {
   },
   orderEntryOperation: getOrderEntryOperation,
   orderFormItems: getOrderFormItems,
+  recommendations,
 }

packages/api/src/platforms/vtex/resolvers/recommendations.ts

@@ -0,0 +1,80 @@
+import { BadRequestError } from '../../errors'
+import type { QueryRecommendationsArgs } from '../../../__generated__/schema'
+import type { GraphqlContext } from '../index'
+import { enhanceSku, type EnhancedSku } from '../utils/enhanceSku'
+import { pickBestSku } from '../utils/sku'
+
+// Structural check for a recommendations campaign VRN
+// (`vrn:recommendations:<account>:<campaign-type>:<campaign-id>`). Kept generic
+// on purpose: the authoritative campaign taxonomy lives in `@faststore/core`,
+// and `@faststore/api` must not depend on it, so we only validate the shape.
+const RECOMMENDATION_VRN_PATTERN = /^vrn:recommendations:[^:]+:[^:]+:[^:]+$/
+
+/**
+ * Resolves personalized recommendations for a campaign.
+ *
+ * The VTEX Recommendations BFF already returns the products fully hydrated in
+ * the same Intelligent Search shape used by the `search` query. We map them
+ * straight to the normalized `StoreProduct` shape (`pickBestSku` + `enhanceSku`)
+ * so recommendation shelves render identical cards to regular shelves, while
+ * preserving the recommendation order returned by the BFF.
+ */
+export const recommendations = async (
+  _: unknown,
+  { campaignVrn, userId, products }: QueryRecommendationsArgs,
+  ctx: GraphqlContext
+) => {
+  const {
+    clients: { commerce },
+  } = ctx
+
+  const { salesChannel } = ctx.storage.channel
+
+  // Validate inputs server-side so only clean, well-formed payloads reach the
+  // Recommendations BFF (see @faststore/api server-side validation principle).
+  const normalizedCampaignVrn = campaignVrn?.trim()
+  if (
+    !normalizedCampaignVrn ||
+    !RECOMMENDATION_VRN_PATTERN.test(normalizedCampaignVrn)
+  ) {
+    throw new BadRequestError(`Invalid campaignVrn: "${campaignVrn}"`)
+  }
+
+  const normalizedUserId = userId?.trim()
+  if (userId != null && !normalizedUserId) {
+    throw new BadRequestError('Invalid userId: must be a non-empty string')
+  }
+
+  if (
+    products != null &&
+    (!Array.isArray(products) || products.some((product) => !product?.trim()))
+  ) {
+    throw new BadRequestError(
+      'Invalid products: must be an array of non-empty strings'
+    )
+  }
+
+  const response = await commerce.recommendation.recommendations({
+    campaignVrn: normalizedCampaignVrn,
+    userId: normalizedUserId || undefined,
+    products: products ?? [],
+    salesChannel: salesChannel ?? undefined,
+    locale: ctx.storage.locale,
+  })
+
+  const { campaign, correlationId } = response
+
+  const orderedProducts = (response.products ?? [])
+    .map((product) => {
+      const sku = pickBestSku(product.items)
+
+      return sku ? enhanceSku(sku, product) : null
+    })
+    .filter((sku): sku is EnhancedSku => Boolean(sku))
+
+  return {
+    products: orderedProducts,
+    correlationId,
+    campaign,
+  }
+}

packages/api/src/platforms/vtex/resolvers/startRecommendationSession.ts

@@ -0,0 +1,30 @@
+import type { GraphqlContext } from '../index'
+
+/**
+ * Starts (or updates) the anonymous personalization session for the current
+ * shopper via the Recommendations BFF.
+ *
+ * The BFF replies with the `vtex-rec-user-id`/`vtex-rec-user-start-session`
+ * Set-Cookie headers, which the client forwards to the browser through
+ * `ctx.storage.cookies`. Returns `true` once the session has been started.
+ */
+export const startRecommendationSession = async (
+  _: unknown,
+  __: unknown,
+  ctx: GraphqlContext
+) => {
+  const result =
+    await ctx.clients.commerce.recommendation.startRecommendationSession()
+
+  // The BFF may not be ready on the first call and can resolve without a
+  // session payload. Only report success once a session actually exists (its
+  // `recommendationsUserId`); otherwise surface an error so the caller retries
+  // instead of treating an empty response as a started session.
+  if (!result?.recommendationsUserId) {
+    throw new Error(
+      'Failed to start recommendation session: no session data returned'
+    )
+  }
+
+  return true
+}

packages/api/src/platforms/vtex/typeDefs/mutation.graphql

@@ -35,4 +35,8 @@ type Mutation {
   startOrderEntryOperation(
     data: IOrderEntryOperation!
   ): StoreOrderEntryOperationResult @auth
+  """
+  Starts an anonymous personalization session for the current shopper.
+  """
+  startRecommendationSession: Boolean!
 }

packages/api/src/platforms/vtex/typeDefs/query.graphql

@@ -529,6 +529,15 @@ type Query {
   Returns the items in an orderForm by its ID.
   """
   orderFormItems(orderFormId: String!): [StoreOrderFormCartItem!]! @auth
+  """
+  Returns personalized product recommendations for a given campaign.
+  """
+  recommendations(
+    campaignVrn: String!
+    userId: String
+    products: [String!]
+  ): RecommendationResponse!
+    @cacheControl(scope: "private", sMaxAge: 120, staleWhileRevalidate: 3600)
 }
 
 type ValidateUserData {

packages/api/src/platforms/vtex/typeDefs/recommendation.graphql

@@ -0,0 +1,11 @@
+type RecommendationResponse {
+  products: [StoreProduct!]!
+  correlationId: String!
+  campaign: RecommendationCampaign!
+}
+
+type RecommendationCampaign {
+  id: String!
+  title: String
+  type: String!
+}

packages/api/test/integration/schema.test.ts

@@ -83,6 +83,7 @@ const QUERIES = [
   'pickupPoints',
   'orderEntryOperation',
   'orderFormItems',
+  'recommendations',
 ]
 
 const MUTATIONS = [
@@ -93,6 +94,7 @@ const MUTATIONS = [
   'processOrderAuthorization',
   'uploadFileToOrderEntry',
   'startOrderEntryOperation',
+  'startRecommendationSession',
 ]
 
 let schema: GraphQLSchema