@faststore/api 4.4.1-dev.0 → 4.5.0-dev.1

package/src/platforms/vtex/clients/commerce/index.ts

@@ -45,11 +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: {
@@ -57,6 +74,84 @@ const BASE_INIT = {
   },
 }
 
+const QUOTE_ISO_DATE = /^\d{4}-\d{2}-\d{2}$/
+const QUOTE_VALID_STATUSES = new Set([
+  'Draft',
+  'Requested',
+  'InReview',
+  'Reviewed',
+  'Approved',
+  'Declined',
+  'Expired',
+  'ConvertedToCart',
+  'ConvertedToOrder',
+])
+
+function validateListUserQuotesArgs({
+  page,
+  perPage,
+  status,
+  createdAtFrom,
+  createdAtTo,
+  expiresAtFrom,
+  expiresAtTo,
+}: ListUserQuotesArgs): void {
+  if (page !== undefined && (!Number.isInteger(page) || page < 1)) {
+    throw new Error(
+      `listUserQuotes: invalid page "${page}" — must be a positive integer`
+    )
+  }
+  if (perPage !== undefined && (!Number.isInteger(perPage) || perPage < 1)) {
+    throw new Error(
+      `listUserQuotes: invalid perPage "${perPage}" — must be a positive integer`
+    )
+  }
+  for (const [field, value] of [
+    ['createdAtFrom', createdAtFrom],
+    ['createdAtTo', createdAtTo],
+    ['expiresAtFrom', expiresAtFrom],
+    ['expiresAtTo', expiresAtTo],
+  ] as [string, string | undefined][]) {
+    if (value && !QUOTE_ISO_DATE.test(value)) {
+      throw new Error(
+        `listUserQuotes: invalid ${field} "${value}" — must be YYYY-MM-DD`
+      )
+    }
+  }
+  if (status && status.length > 0) {
+    const invalid = status.filter((s) => !QUOTE_VALID_STATUSES.has(s))
+    if (invalid.length > 0) {
+      throw new Error(
+        `listUserQuotes: invalid status values: ${invalid.join(', ')}`
+      )
+    }
+  }
+}
+
+function buildListUserQuotesParams({
+  page,
+  perPage,
+  status,
+  createdAtFrom,
+  createdAtTo,
+  expiresAtFrom,
+  expiresAtTo,
+  label,
+}: ListUserQuotesArgs): URLSearchParams {
+  const params = new URLSearchParams()
+
+  if (page) params.append('pageNumber', page.toString())
+  if (perPage) params.append('pageSize', perPage.toString())
+  status?.forEach((s) => params.append('status', s))
+  if (createdAtFrom) params.append('createdAtFrom', createdAtFrom)
+  if (createdAtTo) params.append('createdAtTo', createdAtTo)
+  if (expiresAtFrom) params.append('expiresAtFrom', expiresAtFrom)
+  if (expiresAtTo) params.append('expiresAtTo', expiresAtTo)
+  if (label?.trim()) params.append('label', label.trim())
+
+  return params
+}
+
 export const VtexCommerce = (
   { account, environment, incrementAddress, subDomainPrefix }: Options,
   ctx: GraphqlContext
@@ -77,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> =>
@@ -453,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({
@@ -760,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(
@@ -807,6 +921,27 @@ export const VtexCommerce = (
         )
       },
     },
+    quotes: {
+      listUserQuotes: (args: ListUserQuotesArgs): Promise<QuoteListResult> => {
+        validateListUserQuotesArgs(args)
+
+        const params = buildListUserQuotesParams(args)
+
+        const headers: HeadersInit = withCookie({
+          'content-type': 'application/json',
+          'X-FORWARDED-HOST': forwardedHost,
+        })
+
+        return fetchAPI(
+          `${base}/api/quoting/quotes?${params.toString()}`,
+          {
+            method: 'GET',
+            headers,
+          },
+          { storeCookies }
+        )
+      },
+    },
     vtexid: {
       validate: (): Promise<VtexIdResponse> => {
         const headers: HeadersInit = withCookie({
@@ -985,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/Quote.ts

@@ -0,0 +1,27 @@
+export interface QuoteSummary {
+  id: string
+  status: string
+  label?: string
+  createdAt: string
+  expiresAt: string
+  amount: number
+  createdBy?: string
+}
+
+export interface QuoteListResult {
+  items: QuoteSummary[]
+  pageNumber: number
+  pageSize: number
+  totalItems: number
+}
+
+export interface ListUserQuotesArgs {
+  page?: number
+  perPage?: number
+  status?: string[]
+  createdAtFrom?: string
+  createdAtTo?: string
+  expiresAtFrom?: string
+  expiresAtTo?: string
+  label?: string
+}

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'
@@ -594,6 +603,70 @@ export const Query = {
       paging: orders.paging,
     }
   },
+  listUserQuotes: async (
+    _: unknown,
+    filters: {
+      page?: number
+      perPage?: number
+      status?: string[]
+      createdAtFrom?: string
+      createdAtTo?: string
+      expiresAtFrom?: string
+      expiresAtTo?: string
+      label?: string
+    },
+    ctx: GraphqlContext
+  ) => {
+    const {
+      clients: { commerce },
+    } = ctx
+
+    const result = await commerce.quotes.listUserQuotes(filters)
+
+    const uniqueCreatedByIds = [
+      ...new Set(result.items.map((quote) => quote.createdBy).filter(Boolean)),
+    ] as string[]
+
+    const createdByNameById = new Map<string, string>()
+    await Promise.all(
+      uniqueCreatedByIds.map(async (userId) => {
+        try {
+          const [shopper] = await commerce.masterData.getShopperById({
+            userId,
+          })
+          if (shopper) {
+            const fullName = [shopper.firstName, shopper.lastName]
+              .filter(Boolean)
+              .join(' ')
+            if (fullName) createdByNameById.set(userId, fullName)
+          }
+        } catch {
+          // Fall back to the raw id below if the lookup fails
+        }
+      })
+    )
+
+    const list = result.items.map((quote) => ({
+      id: quote.id,
+      status: quote.status,
+      label: quote.label ?? null,
+      createdAt: quote.createdAt,
+      expiresAt: quote.expiresAt,
+      amount: quote.amount,
+      createdBy: quote.createdBy
+        ? (createdByNameById.get(quote.createdBy) ?? quote.createdBy)
+        : null,
+    }))
+
+    return {
+      list,
+      paging: {
+        total: result.totalItems,
+        currentPage: result.pageNumber,
+        perPage: result.pageSize,
+      },
+    }
+  },
   validateUser: async (_: unknown, __: unknown, _ctx: GraphqlContext) => {
     // Authentication is now handled by @auth directive
     // If we reach here, validation was successful, otherwise an error would have been thrown
@@ -601,6 +674,19 @@ export const Query = {
       isValid: true,
     }
   },
+  isOrganizationMember: async (
+    _: unknown,
+    __: unknown,
+    ctx: GraphqlContext
+  ) => {
+    const {
+      clients: { commerce },
+    } = ctx
+
+    const sessionData = await commerce.session('').catch(() => null)
+
+    return Boolean(sessionData?.namespaces.authentication?.unitId?.value)
+  },
   // only b2b users
   userDetails: async (_: unknown, __: unknown, ctx: GraphqlContext) => {
     const {
@@ -664,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 || '',
@@ -689,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,
@@ -706,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!
+}