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

package/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,26 @@ 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 => {
+    const authToken = getAuthCookie(getUpdatedCookie(ctx) ?? '', account)
+
+    return withCookie({
+      ...additionalHeaders,
+      'X-FORWARDED-HOST': forwardedHost,
+      ...(authToken ? { [`VtexIdclientAutCookie_${account}`]: authToken } : {}),
+    })
+  }
+
   return {
     catalog: {
       salesChannel: (sc: string): Promise<SalesChannel> =>
@@ -532,7 +568,7 @@ export const VtexCommerce = (
 
       params.set(
         'items',
-        'profile.id,profile.email,profile.firstName,profile.lastName,profile.phone,shopper.firstName,shopper.lastName,shopper.organizationManager,store.channel,store.countryCode,store.cultureInfo,store.currencyCode,store.currencySymbol,authentication.customerId,authentication.storeUserId,authentication.storeUserEmail,authentication.unitId,authentication.unitName,checkout.regionId,public.postalCode'
+        'profile.id,profile.email,profile.firstName,profile.lastName,profile.phone,shopper.firstName,shopper.lastName,shopper.organizationManager,shopper.availableContracts,shopper.activeContractId,store.channel,store.countryCode,store.cultureInfo,store.currencyCode,store.currencySymbol,authentication.customerId,authentication.storeUserId,authentication.storeUserEmail,authentication.unitId,authentication.unitName,checkout.regionId,public.postalCode'
       )
 
       const headers: HeadersInit = withCookie({
@@ -839,10 +875,9 @@ export const VtexCommerce = (
           throw new BadRequestError('Missing contractId to fetch CL fields.')
         }
 
-        const headers: HeadersInit = withAppKeyAndToken({
+        const headers: HeadersInit = withBuyerAuthHeaders({
           Accept: 'application/json',
           'content-type': 'application/json',
-          'X-FORWARDED-HOST': forwardedHost,
         })
 
         return fetchAPI(
@@ -1085,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 }
+        )
+      },
+    },
   }
 }

package/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
+}

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

@@ -40,10 +40,19 @@ export interface Profile {
   phone?: Value
 }
 
+export type SessionAvailableContract = {
+  customerId: string
+  contractName: string
+  isActive: boolean
+  isCurrent: boolean
+}
+
 export interface Shopper {
   firstName?: Value
   lastName?: Value
   organizationManager?: { value: boolean }
+  availableContracts?: { value: SessionAvailableContract[] }
+  activeContractId?: Value
 }
 
 export interface Checkout {

package/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,
 }

package/src/platforms/vtex/resolvers/query.ts

@@ -2,6 +2,7 @@ import type {
   ProcessOrderAuthorizationRule,
   QueryAllCollectionsArgs,
   QueryAllProductsArgs,
+  QueryAvailableContractsArgs,
   QueryCollectionArgs,
   QueryListUserOrdersArgs,
   QueryPickupPointsArgs,
@@ -14,10 +15,12 @@ import type {
   QuerySellersArgs,
   QueryShippingArgs,
   QueryUserOrderArgs,
+  StoreContract,
   UserOrderFromList,
 } from '../../../__generated__/schema'
 import { getOrderEntryOperation } from './getOrderEntryOperation'
 import { getOrderFormItems } from './getOrderFormItems'
+import { recommendations } from './recommendations'
 import {
   BadRequestError,
   ForbiddenError,
@@ -31,6 +34,12 @@ import type { SearchArgs } from '../clients/search'
 import type { ProductSearchResult } from '../clients/search/types/ProductSearchResult'
 import type { GraphqlContext } from '../index'
 import { extractRuleForAuthorization } from '../utils/commercialAuth'
+import {
+  mapSessionContractsToStoreContracts,
+  parseSessionAvailableContracts,
+  resolveActiveContractDisplayName,
+  resolveActiveContractIdFromSession,
+} from '../utils/contract'
 import { mutateChannelContext, mutateLocaleContext } from '../utils/contex'
 import { getAuthCookie, parseJwt } from '../utils/cookies'
 import { enhanceSku } from '../utils/enhanceSku'
@@ -741,9 +750,7 @@ export const Query = {
         contractId: profile?.id?.value ?? '',
       })
 
-      const name =
-        contract?.corporateName ??
-        `${(profile?.firstName?.value ?? '').trim()} ${(profile?.lastName?.value ?? '').trim()}`.trim()
+      const name = resolveActiveContractDisplayName(contract, profile)
 
       return {
         name: name || '',
@@ -766,6 +773,55 @@ export const Query = {
       // createdAt: '',
     }
   },
+  // only b2b users
+  // Contract list from VTEX session `shopper.availableContracts`.
+  availableContracts: async (
+    _: unknown,
+    { orgUnitId }: QueryAvailableContractsArgs,
+    ctx: GraphqlContext
+  ): Promise<StoreContract[]> => {
+    if (!orgUnitId) {
+      throw new BadRequestError('Missing orgUnitId')
+    }
+
+    const {
+      account,
+      headers,
+      clients: { commerce },
+    } = ctx
+
+    const sessionData = await commerce.session('').catch(() => null)
+    const authToken = getAuthCookie(headers?.cookie ?? '', account)
+    let jwt: ReturnType<typeof parseJwt> = null
+
+    try {
+      jwt = authToken ? parseJwt(authToken) : null
+    } catch {
+      jwt = null
+    }
+
+    const sessionUnitId =
+      sessionData?.namespaces.authentication?.unitId?.value?.trim() ??
+      jwt?.unitId?.trim() ??
+      ''
+
+    if (!sessionUnitId || sessionUnitId !== orgUnitId) {
+      throw new ForbiddenError(
+        'You are not allowed to list contracts for this organization unit'
+      )
+    }
+
+    const contracts = parseSessionAvailableContracts(
+      sessionData?.namespaces.shopper
+    )
+
+    const activeContractId =
+      resolveActiveContractIdFromSession(sessionData) ||
+      jwt?.customerId?.trim() ||
+      ''
+
+    return mapSessionContractsToStoreContracts(contracts, activeContractId)
+  },
   pickupPoints: async (
     _: unknown,
     { geoCoordinates }: QueryPickupPointsArgs,
@@ -783,4 +839,5 @@ export const Query = {
   },
   orderEntryOperation: getOrderEntryOperation,
   orderFormItems: getOrderFormItems,
+  recommendations,
 }

package/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,
+  }
+}

package/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
+}

package/src/platforms/vtex/resolvers/validateSession.ts

@@ -7,6 +7,7 @@ import type {
   StoreSession,
 } from '../../../__generated__/schema'
 import ChannelMarshal from '../utils/channel'
+import { resolveActiveContractDisplayName } from '../utils/contract'
 import { getAuthCookie, parseJwt } from '../utils/cookies'
 
 async function getPreciseLocationData(
@@ -198,7 +199,7 @@ export const validateSession = async (
             `${typeof shopper?.firstName?.value === 'string' ? shopper.firstName.value : ''} ${typeof shopper?.lastName?.value === 'string' ? shopper.lastName.value : ''}`.trim(),
           userEmail: authentication?.storeUserEmail.value ?? '',
           savedPostalCode: publicData?.postalCode?.value ?? '',
-          contractName: contract?.corporateName ?? '',
+          contractName: resolveActiveContractDisplayName(contract, profile),
           organizationManager: shopper?.organizationManager?.value ?? false,
         }
       : null,

package/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!
 }

package/src/platforms/vtex/typeDefs/organization.graphql

@@ -17,3 +17,21 @@ input IStoreOrganization {
   """
   identifier: String!
 }
+
+"""
+A commercial contract available to a buyer's Organization Unit.
+"""
+type StoreContract {
+  """
+  Contract identifier (the contract/scope ID associated with the Organization Unit).
+  """
+  id: ID!
+  """
+  Human-readable corporate name of the contract (resolved from MasterData).
+  """
+  corporateName: String!
+  """
+  Indicates whether this contract is the one currently active in the session.
+  """
+  isActive: Boolean!
+}

package/src/platforms/vtex/typeDefs/query.graphql

@@ -491,6 +491,18 @@ type Query {
     @auth
     @cacheControl(scope: "private", sMaxAge: 300, staleWhileRevalidate: 3600)
 
+  """
+  Lists the commercial contracts associated with the given Organization Unit,
+  resolved to human-readable corporate names. Governed: only contracts associated
+  with the authenticated buyer's Organization Unit are returned.
+  """
+  availableContracts(
+    """
+    The Organization Unit identifier whose contracts will be listed.
+    """
+    orgUnitId: String!
+  ): [StoreContract!]! @auth @cacheControl(scope: "private", sMaxAge: 0)
+
   """
   Returns whether the current authenticated user belongs to a B2B organization unit.
   """
@@ -517,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 {

package/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!
+}

package/src/platforms/vtex/utils/contract.ts

@@ -0,0 +1,144 @@
+import type { ContractResponse } from '../clients/commerce/Contract'
+import type {
+  SessionAvailableContract,
+  Shopper,
+} from '../clients/commerce/types/Session'
+
+type ProfileNameFields = {
+  firstName?: { value?: string | null } | null
+  lastName?: { value?: string | null } | null
+} | null
+
+/**
+ * Display name from Master Data, aligned with buyer-portal `personalDataToContract`.
+ */
+export const resolveContractDisplayNameFromMd = (
+  contract: ContractResponse | null | undefined
+): string => {
+  const corporateName = (contract?.corporateName ?? '').trim()
+
+  if (corporateName) {
+    return corporateName
+  }
+
+  return (contract?.firstName ?? '').trim()
+}
+
+const isSessionAvailableContract = (
+  value: unknown
+): value is SessionAvailableContract => {
+  if (!value || typeof value !== 'object') {
+    return false
+  }
+
+  const contract = value as Record<string, unknown>
+
+  return (
+    typeof contract.customerId === 'string' &&
+    contract.customerId.trim() !== '' &&
+    typeof contract.contractName === 'string' &&
+    typeof contract.isActive === 'boolean' &&
+    typeof contract.isCurrent === 'boolean'
+  )
+}
+
+/**
+ * Parses VTEX session `shopper.availableContracts` into a typed list.
+ */
+export const parseSessionAvailableContracts = (
+  shopper: Shopper | null | undefined
+): SessionAvailableContract[] => {
+  const raw = shopper?.availableContracts?.value
+
+  if (!Array.isArray(raw)) {
+    return []
+  }
+
+  return raw.filter(isSessionAvailableContract)
+}
+
+/**
+ * Whether a session contract is eligible for the switcher list.
+ */
+export const isSwitchableSessionContract = (
+  contract: SessionAvailableContract | null | undefined
+): boolean => {
+  if (!contract?.customerId) {
+    return false
+  }
+
+  const name = (contract.contractName ?? '').trim()
+
+  return Boolean(name && contract.isActive)
+}
+
+/**
+ * Resolves the active contract id from VTEX session namespaces.
+ */
+export const resolveActiveContractIdFromSession = (
+  sessionData: {
+    namespaces?: {
+      shopper?: Shopper | null
+      authentication?: { customerId?: { value?: string | null } | null } | null
+      profile?: { id?: { value?: string | null } | null } | null
+    } | null
+  } | null
+): string => {
+  return (
+    sessionData?.namespaces?.shopper?.activeContractId?.value?.trim() ??
+    sessionData?.namespaces?.authentication?.customerId?.value?.trim() ??
+    sessionData?.namespaces?.profile?.id?.value?.trim() ??
+    ''
+  )
+}
+
+/**
+ * Maps session contracts to GraphQL `StoreContract` entries.
+ */
+export const mapSessionContractsToStoreContracts = (
+  contracts: SessionAvailableContract[],
+  activeContractId = ''
+): Array<{ id: string; corporateName: string; isActive: boolean }> => {
+  const normalizedActiveId = activeContractId.trim()
+
+  return contracts.filter(isSwitchableSessionContract).map((contract) => ({
+    id: contract.customerId,
+    corporateName: contract.contractName.trim(),
+    isActive: normalizedActiveId
+      ? contract.customerId === normalizedActiveId
+      : contract.isCurrent,
+  }))
+}
+
+/**
+ * Whether a CL record is eligible for contract switcher summaries (attached list).
+ */
+export const isSwitchableContractSummary = (
+  contract: ContractResponse | null | undefined
+): boolean => {
+  if (!contract) {
+    return false
+  }
+
+  const name = resolveContractDisplayNameFromMd(contract)
+  const email = (contract.email ?? '').trim()
+
+  return Boolean(name && email)
+}
+
+/**
+ * Resolves the active contract name: Master Data first, then VTEX session profile.
+ * Matches `accountProfile` / buyer-portal behavior when CL lookup fails.
+ */
+export const resolveActiveContractDisplayName = (
+  contract: ContractResponse | null | undefined,
+  profile: ProfileNameFields
+): string => {
+  const fromMasterData = resolveContractDisplayNameFromMd(contract)
+
+  if (fromMasterData) {
+    return fromMasterData
+  }
+
+  return (profile?.firstName?.value ?? '').trim()
+}