feat(core): add RecommendationShelf section with personalization tracking

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

@@ -1,15 +1,18 @@
 import type { GraphqlContext } from '..'
 import { VtexCommerce } from './commerce'
+import { Recommendation } from './recommendation'
 import { IntelligentSearch } from './search'
 
 export type Clients = ReturnType<typeof getClients>
 
 export const getClients = (options: Options, ctx: GraphqlContext) => {
   const search = IntelligentSearch(options, ctx)
   const commerce = VtexCommerce(options, ctx)
+  const recommendation = Recommendation(options, ctx)
 
   return {
     search,
     commerce,
+    recommendation,
   }
 }

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

@@ -0,0 +1,83 @@
+import type { GraphqlContext } from '../..'
+import { getStoreCookie, getWithCookie } from '../../utils/cookies'
+import { fetchAPI } from '../fetch'
+import type {
+  RecommendationResult,
+  StartRecommendationSessionResult,
+} from './types/RecommendationResult'
+
+// Identifies the storefront origin to the Recommendations BFF, as required by
+// the API (`x-vtex-rec-origin` header).
+const REC_ORIGIN_SUFFIX = 'storefront/vtex.recommendation-shelf@2.x'
+
+export interface RecommendationArgs {
+  campaignVrn: string
+  userId?: string
+  products?: string[]
+  salesChannel?: string
+  locale?: string
+}
+
+export const Recommendation = (
+  { account, environment }: Options,
+  ctx: GraphqlContext
+) => {
+  const base = `https://${account}.${environment}.com.br/api/recommend-bff/v2`
+  const withCookie = getWithCookie(ctx)
+  const storeCookies = getStoreCookie(ctx)
+
+  const headers: HeadersInit = withCookie({
+    accept: 'application/json',
+    'content-type': 'application/json',
+    'x-vtex-rec-origin': `${account}/${REC_ORIGIN_SUFFIX}`,
+  })
+
+  const 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(`${base}/recommendations?${params.toString()}`, { headers })
+  }
+
+  // Starts/updates the anonymous personalization session. The BFF resolves the
+  // orderForm from the forwarded `checkout.vtex.com` cookie and replies with the
+  // `vtex-rec-user-id`/`vtex-rec-user-start-session` Set-Cookie headers, which we
+  // forward to the browser through `ctx.storage.cookies`.
+  const startRecommendationSession = (): Promise<
+    StartRecommendationSessionResult | undefined
+  > => {
+    const params = new URLSearchParams({ an: account })
+
+    return fetchAPI(
+      `${base}/users/start-session?${params.toString()}`,
+      { method: 'POST', headers },
+      { storeCookies }
+    )
+  }
+
+  return {
+    recommendations,
+    startRecommendationSession,
+  }
+}

packages/api/src/platforms/vtex/clients/recommendation/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

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

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

@@ -0,0 +1,49 @@
+import type { QueryRecommendationsArgs } from '../../../__generated__/schema'
+import type { GraphqlContext } from '../index'
+import { enhanceSku, type EnhancedSku } from '../utils/enhanceSku'
+import { pickBestSku } from '../utils/sku'
+
+/**
+ * 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: { recommendation },
+  } = ctx
+
+  const { salesChannel } = ctx.storage.channel
+
+  const response = await recommendation.recommendations({
+    campaignVrn,
+    userId: userId ?? 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,19 @@
+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
+) => {
+  await ctx.clients.recommendation.startRecommendationSession()
+
+  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

@@ -470,6 +470,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

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