Feat(VTEX): Recommendations BFF API

vtex/actions/events/productView.ts

@@ -0,0 +1,61 @@
+import type { AppContext } from "../../mod.ts";
+import { getOrigin, parseCookie } from "../../utils/recommendations.ts";
+import type { ProductViewSource } from "../../utils/types.ts";
+
+interface Props {
+  /**
+   * @title User ID
+   * @description The ID of the user who viewed the recommendation.
+   */
+  userId?: string;
+  /**
+   * @title Product ID
+   * @description The ID of the product that was clicked.
+   */
+  productId: string;
+  /**
+   * @title Source
+   * @description The source of the product view event.
+   */
+  source: ProductViewSource;
+  /**
+   * @description The origin of the recommendation request. E.g: apiexamples/storefront/vtex.recommendation-shelf@2.x
+   */
+  "x-vtex-rec-origin"?: string;
+}
+
+export default async function loader(
+  props: Props,
+  req: Request,
+  ctx: AppContext,
+) {
+  const { bff } = ctx;
+
+  const origin = getOrigin(req, ctx.account, props["x-vtex-rec-origin"]);
+  if (!origin) {
+    throw new Error("x-vtex-rec-origin header is required");
+  }
+
+  const cookies = parseCookie(req.headers);
+  const userId = props.userId ?? cookies?.userId;
+
+  if (!userId) {
+    throw new Error("userId is required");
+  }
+
+  await bff["POST /api/recommend-bff/v2/events/product-view"]({
+    an: ctx.account,
+  }, {
+    body: {
+      userId,
+      product: props.productId,
+      source: props.source,
+    },
+    headers: {
+      "x-vtex-rec-origin": origin,
+      "user-agent": req.headers.get("user-agent") || "",
+    },
+  });
+
+  return { ok: true };
+}

vtex/actions/events/recommendationClick.ts

@@ -0,0 +1,59 @@
+import { AppContext } from "../../mod.ts";
+import { getOrigin, parseCookie } from "../../utils/recommendations.ts";
+
+interface Props {
+  /**
+   * @title User ID
+   * @description The ID of the user who viewed the recommendation.
+   */
+  userId?: string;
+  /**
+   * @title Product ID
+   * @description The ID of the product that was clicked.
+   */
+  productId: string;
+  /**
+   * @title Correlation ID
+   * @description The correlation ID of the recommendation request.
+   */
+  correlationId: string;
+  /**
+   * @description The origin of the recommendation request. E.g: apiexamples/storefront/vtex.recommendation-shelf@2.x
+   */
+  "x-vtex-rec-origin"?: string;
+}
+
+export default async function loader(
+  props: Props,
+  req: Request,
+  ctx: AppContext,
+) {
+  const { bff } = ctx;
+
+  const origin = getOrigin(req, ctx.account, props["x-vtex-rec-origin"]);
+  if (!origin) {
+    throw new Error("x-vtex-rec-origin header is required");
+  }
+
+  const cookies = parseCookie(req.headers);
+  const userId = props.userId ?? cookies?.userId;
+
+  if (!userId) {
+    throw new Error("userId is required");
+  }
+
+  await bff["POST /api/recommend-bff/v2/events/recommendation-click"]({
+    an: ctx.account,
+  }, {
+    body: {
+      correlationId: props.correlationId,
+      userId,
+      product: props.productId,
+    },
+    headers: {
+      "x-vtex-rec-origin": origin,
+    },
+  });
+
+  return { ok: true };
+}

vtex/actions/events/recommendationView.ts

@@ -0,0 +1,59 @@
+import { AppContext } from "../../mod.ts";
+import { getOrigin, parseCookie } from "../../utils/recommendations.ts";
+
+interface Props {
+  /**
+   * @title User ID
+   * @description The ID of the user who viewed the recommendation.
+   */
+  userId?: string;
+  /**
+   * @title Correlation ID
+   * @description The correlation ID of the recommendation request.
+   */
+  correlationId: string;
+  /**
+   * @title Products
+   * @description The products SKU IDs that were viewed.
+   */
+  products: string[];
+  /**
+   * @description The origin of the recommendation request. E.g: apiexamples/storefront/vtex.recommendation-shelf@2.x
+   */
+  "x-vtex-rec-origin"?: string;
+}
+
+export default async function loader(
+  props: Props,
+  req: Request,
+  ctx: AppContext,
+) {
+  const { bff } = ctx;
+
+  const origin = getOrigin(req, ctx.account, props["x-vtex-rec-origin"]);
+  if (!origin) {
+    throw new Error("x-vtex-rec-origin header is required");
+  }
+
+  const cookies = parseCookie(req.headers);
+  const userId = props.userId ?? cookies?.userId;
+
+  if (!userId) {
+    throw new Error("userId is required");
+  }
+
+  await bff["POST /api/recommend-bff/v2/events/recommendation-view"]({
+    an: ctx.account,
+  }, {
+    body: {
+      correlationId: props.correlationId,
+      userId,
+      products: props.products,
+    },
+    headers: {
+      "x-vtex-rec-origin": origin,
+    },
+  });
+
+  return { ok: true };
+}

vtex/actions/recommendation/startSession.ts

@@ -0,0 +1,43 @@
+import { getSetCookies } from "std/http/cookie.ts";
+import type { AppContext } from "../../mod.ts";
+import { proxySetCookie } from "../../utils/cookies.ts";
+import { parseCookie } from "../../utils/orderForm.ts";
+
+export default async function action(
+  _: unknown,
+  req: Request,
+  ctx: AppContext,
+) {
+  const { bff } = ctx;
+  const { orderFormId } = parseCookie(req.headers);
+
+  const url = new URL(req.url);
+  const host = url.host;
+
+  const headers = new Headers();
+  headers.set(
+    "x-vtex-rec-origin",
+    `${ctx.account}/storefront/deco.recommendations@1.x`,
+  );
+  headers.set("x-forwarded-host", host);
+  headers.set("host", `${ctx.account}.vtexcommercestable.com.br`);
+
+  const cookie = req.headers.get("cookie");
+  if (cookie) {
+    headers.set("cookie", cookie);
+  }
+
+  const response = await bff["POST /api/recommend-bff/v2/users/start-session"]({
+    an: ctx.account,
+  }, {
+    body: { orderFormId },
+    headers,
+  });
+
+  const data = await response.json();
+
+  console.log(data, getSetCookies(response.headers));
+  proxySetCookie(response.headers, ctx.response.headers, req.url);
+
+  return data;
+}

vtex/loaders/recommendations/productList.ts

@@ -0,0 +1,169 @@
+import { Product } from "../../../commerce/types.ts";
+import { AppContext } from "../../mod.ts";
+import { getOrigin, parseCookie } from "../../utils/recommendations.ts";
+import { getSegmentFromBag, withSegmentCookie } from "../../utils/segment.ts";
+import { toProduct } from "../../utils/transform.ts";
+import {
+  CampaignType,
+  LegacyProduct,
+  ProductListToId,
+} from "../../utils/types.ts";
+import { getFirstItemAvailable } from "../legacy/productListingPage.ts";
+
+type CampaignTypeLabel =
+  | "Best sellers"
+  | "Personalized recommendations"
+  | "Similar items"
+  | "Cross-sell"
+  | "Cart-based recommendations"
+  | "Last seen"
+  | "Recent interactions"
+  | "Visual similarity"
+  | "Search-based recommendations"
+  | "Next interaction";
+
+const campaignTypeMap: Record<CampaignTypeLabel, CampaignType> = {
+  "Best sellers": "rec-top-items-v2",
+  "Personalized recommendations": "rec-persona-v2",
+  "Similar items": "rec-similar-v2",
+  "Cross-sell": "rec-cross-v2",
+  "Cart-based recommendations": "rec-cart-v2",
+  "Last seen": "rec-last-v2",
+  "Recent interactions": "rec-interactions-v2",
+  "Visual similarity": "rec-visual-v2",
+  "Search-based recommendations": "rec-search-v2",
+  "Next interaction": "rec-next-v2",
+};
+
+interface Props {
+  /**
+   * @title Campaign Type
+   * @description The type of campaign to fetch recommendations for.
+   */
+  campaignType: CampaignTypeLabel;
+  /**
+   * @title Campaign ID
+   * @description Contact https://supporticket.vtex.com/support to get the campaign ID.
+   */
+  campaignId: string;
+  /**
+   * @title Products
+   * @description List of product IDs for context-based recommendations. For similar items and cross-sell, send only one product ID. For cart recommendations, send all product IDs in the user's cart.
+   */
+  products?: ProductListToId;
+  /**
+   * @title Zip Code
+   * @description Zip code for location-based recommendations. If not provided, it is extracted from the segment cookie.
+   */
+  zipCode?: string;
+  /**
+   * @title Pickup Point
+   * @description Pickup point identifier for location-based recommendations. If not provided, it is extracted from the segment cookie.
+   */
+  pickupPoint?: string;
+  /**
+   * @title Region ID
+   * @description Region identifier for location-based recommendations. If not provided, it is extracted from the segment cookie.
+   */
+  regionId?: string;
+  /**
+   * @ignore true
+   */
+  "x-vtex-rec-origin"?: string;
+}
+
+/**
+ * @title VTEX Recommendations Product List
+ * @description Get a list of products from the VTEX Recommendations API
+ */
+export default async function loader(
+  props: Props,
+  req: Request,
+  ctx: AppContext,
+): Promise<Product[] | null> {
+  try {
+    const { bff, account } = ctx;
+
+    const origin = getOrigin(req, ctx.account, props["x-vtex-rec-origin"]);
+    const segment = getSegmentFromBag(ctx);
+    const cookies = parseCookie(req.headers);
+
+    let userId = cookies?.userId;
+
+    if (ctx.advancedConfigs?.autoStartRecommendationSession && !userId) {
+      const response = await ctx.invoke.vtex.actions.recommendation
+        .startSession();
+      userId = response.recommendationsUserId;
+    }
+
+    const campaignType = campaignTypeMap[props.campaignType];
+    const campaignVrn =
+      `vrn:recommendations:${account}:${campaignType}:${props.campaignId}`;
+
+    // From vtex docs:
+    // "For similar items and cross-sell, send only one product ID.
+    // For cart recommendations, send all product IDs in the user's cart."
+    const products =
+      campaignType === "rec-cross-v2" || campaignType === "rec-similar-v2"
+        ? [props.products?.[0]]
+        : props.products;
+
+    const productIds = products?.filter(Boolean).join(",");
+
+    const response = await bff["GET /api/recommend-bff/v2/recommendations"]({
+      an: account,
+      campaignVrn,
+      pickupPoint: props.pickupPoint,
+      regionId: props.regionId,
+      zipCode: props.zipCode,
+      userId,
+      products: productIds,
+      salesChannel: segment?.payload?.channel || ctx.salesChannel,
+    }, {
+      headers: { ...withSegmentCookie(segment), "x-vtex-rec-origin": origin },
+    }).then((res) => res.json());
+
+    const baseUrl = new URL(req.url).origin;
+
+    return (response.products as unknown as LegacyProduct[]).map((product) =>
+      toProduct(
+        product,
+        product.items.find(getFirstItemAvailable) ?? product.items[0],
+        0,
+        {
+          baseUrl,
+          priceCurrency: segment?.payload?.currencyCode ?? "BRL",
+          isVariantOfAdditionalProperty: [
+            {
+              "@type": "PropertyValue",
+              name: "correlationId",
+              value: response.correlationId,
+              valueReference: "RECOMMENDATION",
+            },
+            {
+              "@type": "PropertyValue",
+              name: "campaignId",
+              value: response.campaign?.id,
+              valueReference: "RECOMMENDATION",
+            },
+            {
+              "@type": "PropertyValue",
+              name: "campaignTitle",
+              value: response.campaign?.title,
+              valueReference: "RECOMMENDATION",
+            },
+            {
+              "@type": "PropertyValue",
+              name: "campaignType",
+              value: response.campaign?.type,
+              valueReference: "RECOMMENDATION",
+            },
+          ],
+        },
+      )
+    );
+  } catch (error) {
+    console.error(error);
+    return null;
+  }
+}