@vtex/faststore-plugin-buyer-portal 1.3.26 → 1.3.28

package/src/features/shared/services/logger/analytics/analytics.ts

@@ -0,0 +1,101 @@
+import storeConfig from "discovery.config";
+
+import { isDevelopment } from "../../../utils/environment";
+
+import type { DataIngestionApiFields, DataIngestionApiParams } from "./types";
+
+/**
+ * VTEX Data Ingestion API for Analytics
+ * https://internal-docs.vtex.com/Analytics/VTEX-Data-Platform/data-ingestion-API/
+ */
+
+export const APP_NAME = "b2b-organization-account";
+
+/**
+ * Send event to VTEX Data Ingestion API
+ */
+export async function dataIngestionApi(
+  fields: DataIngestionApiParams
+): Promise<void> {
+  const isDevEnvironment = fields.workspace !== "master";
+
+  delete fields.workspace;
+
+  const isInsideVtexNetwork = false;
+  const endpoint = isInsideVtexNetwork
+    ? "https://analytics.vtex.com/api/analytics/schemaless-events"
+    : "https://rc.vtex.com/api/analytics/schemaless-events";
+
+  try {
+    await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        name: APP_NAME,
+        ...fields,
+      }),
+    });
+  } catch (error) {
+    if (isDevEnvironment) {
+      console.warn(
+        `Error when sending analytics data for "${fields.event_name}".`,
+        error
+      );
+    }
+  }
+}
+
+/**
+ * Get common analytics context
+ */
+function getCommonAnalyticsContext() {
+  const account = storeConfig?.api?.storeId || "unknown";
+  const locale =
+    typeof window !== "undefined"
+      ? window.navigator.language || "undefined"
+      : "undefined";
+  const production = !isDevelopment();
+
+  // Detect device type
+  let device = "desktop";
+  if (typeof window !== "undefined") {
+    const userAgent = window.navigator.userAgent.toLowerCase();
+    device =
+      /mobile|android|iphone|ipad|ipod|blackberry|iemobile|opera mini/i.test(
+        userAgent
+      )
+        ? "mobile"
+        : "desktop";
+  }
+
+  return {
+    account,
+    locale,
+    production,
+    device,
+  };
+}
+
+/**
+ * Hook to send analytics events
+ * This is a simple version that will be extended by useAnalytics hook
+ */
+export function useDataIngestionApi() {
+  const commonFields = getCommonAnalyticsContext();
+
+  const sendEvent = (fields: DataIngestionApiFields) => {
+    // Get workspace from environment
+    const workspace = isDevelopment() ? "dev" : "master";
+
+    dataIngestionApi({
+      ...commonFields,
+      event_category: fields.event_category || "click",
+      ...fields,
+      workspace,
+    });
+  };
+
+  return { sendEvent };
+}

package/src/features/shared/services/logger/analytics/constants.ts

@@ -0,0 +1,83 @@
+/**
+ * Event name constants for consistent tracking
+ */
+export const ANALYTICS_EVENTS = {
+  // Budget events
+  BUDGET_CREATED: "budget_created",
+  BUDGET_EDITED: "budget_edited",
+  BUDGET_DELETED: "budget_deleted",
+  BUDGET_CREATE_ERROR: "budget_create_error",
+  BUDGET_EDIT_ERROR: "budget_edit_error",
+  BUDGET_DELETE_ERROR: "budget_delete_error",
+  BUDGET_STEP_TIMING: "budget_step_timing",
+  BUDGET_FLOW_COMPLETED: "budget_flow_completed",
+
+  // Buying Policy events
+  BUYING_POLICY_CREATED: "buying_policy_created",
+  BUYING_POLICY_EDITED: "buying_policy_edited",
+  BUYING_POLICY_DELETED: "buying_policy_deleted",
+  BUYING_POLICY_CREATE_ERROR: "buying_policy_create_error",
+  BUYING_POLICY_EDIT_ERROR: "buying_policy_edit_error",
+  BUYING_POLICY_DELETE_ERROR: "buying_policy_delete_error",
+  BUYING_POLICY_STEP_TIMING: "buying_policy_step_timing",
+  BUYING_POLICY_FLOW_COMPLETED: "buying_policy_flow_completed",
+
+  // Custom Field events
+  CUSTOM_FIELD_CREATED: "custom_field_created",
+  CUSTOM_FIELD_EDITED: "custom_field_edited",
+  CUSTOM_FIELD_DELETED: "custom_field_deleted",
+  CUSTOM_FIELD_CREATE_ERROR: "custom_field_create_error",
+  CUSTOM_FIELD_EDIT_ERROR: "custom_field_edit_error",
+  CUSTOM_FIELD_DELETE_ERROR: "custom_field_delete_error",
+
+  // Address events
+  ADDRESS_CREATED: "address_created",
+  ADDRESS_EDITED: "address_edited",
+  ADDRESS_DELETED: "address_deleted",
+  ADDRESS_CREATE_ERROR: "address_create_error",
+  ADDRESS_EDIT_ERROR: "address_edit_error",
+  ADDRESS_DELETE_ERROR: "address_delete_error",
+  ADDRESS_STEP_TIMING: "address_step_timing",
+
+  // Location events
+  LOCATION_CREATED: "location_created",
+  LOCATION_EDITED: "location_edited",
+  LOCATION_DELETED: "location_deleted",
+  LOCATION_CREATE_ERROR: "location_create_error",
+  LOCATION_EDIT_ERROR: "location_edit_error",
+  LOCATION_DELETE_ERROR: "location_delete_error",
+
+  // Recipient events
+  RECIPIENT_CREATED: "recipient_created",
+  RECIPIENT_EDITED: "recipient_edited",
+  RECIPIENT_DELETED: "recipient_deleted",
+  RECIPIENT_CREATE_ERROR: "recipient_create_error",
+  RECIPIENT_EDIT_ERROR: "recipient_edit_error",
+  RECIPIENT_DELETE_ERROR: "recipient_delete_error",
+
+  // User events
+  USER_CREATED: "user_created",
+  USER_EDITED: "user_edited",
+  USER_DELETED: "user_deleted",
+  USER_CREATE_ERROR: "user_create_error",
+  USER_EDIT_ERROR: "user_edit_error",
+  USER_DELETE_ERROR: "user_delete_error",
+
+  // Organization Unit events
+  ORG_UNIT_CREATED: "org_unit_created",
+  ORG_UNIT_EDITED: "org_unit_edited",
+  ORG_UNIT_DELETED: "org_unit_deleted",
+  ORG_UNIT_CREATE_ERROR: "org_unit_create_error",
+  ORG_UNIT_EDIT_ERROR: "org_unit_edit_error",
+  ORG_UNIT_DELETE_ERROR: "org_unit_delete_error",
+
+  // Interaction events
+  TOOLTIP_INTERACTION: "tooltip_interaction",
+  STEP_CHANGE: "step_change",
+
+  // Generic events
+  ENTITY_CREATED: "entity_created",
+  ENTITY_EDITED: "entity_edited",
+  ENTITY_ERROR: "entity_error",
+  TIMER_COMPLETED: "timer_completed",
+} as const;

package/src/features/shared/services/logger/analytics/types.ts

@@ -0,0 +1,108 @@
+/**
+ * Analytics event categories
+ */
+export type EventCategory =
+  | "click"
+  | "view"
+  | "apiAnswer"
+  | "webVitals"
+  | "creation"
+  | "edition"
+  | "error"
+  | "timing"
+  | "interaction";
+
+/**
+ * Analytics event fields
+ */
+export interface DataIngestionApiFields {
+  /** The type of the event */
+  event_category?: EventCategory;
+  /** The name of the event. Has to be unique through the app. */
+  event_name: string;
+  /** Additional informations */
+  /** Time spent on page */
+  time_on_page?: number;
+  /** Additional metadata about the event */
+  metadata?: Record<string, unknown>;
+  /** Entity type (e.g., 'budget', 'buying_policy') */
+  entity_type?: string;
+  /** Entity ID */
+  entity_id?: string;
+  /** Is this a new entity? */
+  is_new?: boolean;
+  /** Duration in milliseconds */
+  duration_ms?: number;
+  /** Step name for multi-step flows */
+  step_name?: string;
+  /** Flow name for multi-step flows */
+  flow_name?: string;
+  /** Component type for interactions */
+  component_type?: string;
+  /** Action performed */
+  action?: string;
+}
+
+/**
+ * Internal params for data ingestion API
+ */
+export interface DataIngestionApiParams {
+  [key: string]: string | number | boolean | object | undefined;
+  workspace?: string;
+}
+
+/**
+ * Step timing properties
+ */
+export interface StepTimingProperties {
+  flow_name: string;
+  step_name: string;
+  from_step?: string;
+  to_step?: string;
+  duration_ms: number;
+  step_index?: number;
+  total_steps?: number;
+}
+
+/**
+ * Error tracking properties
+ */
+export interface ErrorEventProperties {
+  error_message: string;
+  error_type?: string;
+  error_stack?: string;
+  entity_type?: string;
+  entity_id?: string;
+  is_new_entity: boolean;
+  operation?: string; // create, update, delete
+}
+
+/**
+ * Interaction properties
+ */
+export interface InteractionEventProperties {
+  component_type: string;
+  component_id?: string;
+  action: string;
+  selected_option?: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Generic entity creation properties
+ */
+export interface EntityCreatedProperties {
+  entity_type: string;
+  entity_id?: string;
+  properties: Record<string, unknown>;
+}
+
+/**
+ * Generic entity edition properties
+ */
+export interface EntityEditedProperties {
+  entity_type: string;
+  entity_id: string;
+  changed_fields?: string[];
+  properties: Record<string, unknown>;
+}

package/src/features/shared/services/logger/index.ts

@@ -2,3 +2,4 @@ export * from "./types";
 export * from "./constants";
 export * from "./context";
 export * from "./otlp-logger.service";
+export * from "./analytics/analytics";

package/src/features/shared/utils/constants.ts

@@ -13,4 +13,4 @@ export const LOCAL_STORAGE_LOCATION_EDIT_KEY = "bp_hide_edit_location_confirm";
 export const LOCAL_STORAGE_RECIPIENT_EDIT_KEY =
   "bp_hide_edit_recipient_confirm";
 
-export const CURRENT_VERSION = "1.3.26";
+export const CURRENT_VERSION = "1.3.28";

package/src/features/users/components/CreateUserDrawer/CreateUserDrawer.tsx

@@ -12,6 +12,8 @@ import {
   Icon,
   InputText,
 } from "../../../shared/components";
+import { useAnalytics } from "../../../shared/hooks";
+import { ANALYTICS_EVENTS } from "../../../shared/services/logger/analytics/constants";
 import { buyerPortalRoutes } from "../../../shared/utils/buyerPortalRoutes";
 import { maskPhoneNumber } from "../../../shared/utils/phoneNumber";
 import { useAddUserToOrgUnit } from "../../hooks";
@@ -31,6 +33,11 @@ export const CreateUserDrawer = ({
 }: CreateUserDrawerProps) => {
   const { pushToast } = useUI();
   const router = useRouter();
+  const { trackEntityCreated, trackEntityCreateError } = useAnalytics({
+    entityType: "user",
+    defaultTimerName: "user_creation",
+    shouldTrackDefaultTimer: true,
+  });
   const [drawerState, setDrawerState] = useState<
     "CREATE_USER" | "USER_ALREADY_EXISTS"
   >("CREATE_USER");
@@ -74,6 +81,15 @@ export const CreateUserDrawer = ({
   };
 
   const handleAddUserSuccess = ({ user }: { user: { id: string } }) => {
+    trackEntityCreated(ANALYTICS_EVENTS.USER_CREATED, "user", {
+      user_name: name,
+      user_email: email,
+      user_phone: phone,
+      roles_count: roles.length,
+      role_ids: roles,
+      org_unit_id: orgUnitId,
+    });
+
     pushToast({
       message: "User successfully added",
       status: "INFO",
@@ -112,6 +128,14 @@ export const CreateUserDrawer = ({
         };
       };
 
+      trackEntityCreateError(ANALYTICS_EVENTS.USER_CREATE_ERROR, err, {
+        org_unit_id: orgUnitId,
+        error_type:
+          error.code === "USER_ALREADY_EXISTS"
+            ? "user_already_exists"
+            : "unknown",
+      });
+
       setUserAlreadyInUse({
         ...error.user,
         orgUnit: error.orgUnit,

package/src/features/users/components/DeleteUserDrawer/DeleteUserDrawer.tsx

@@ -8,6 +8,8 @@ import {
   InputText,
   type BasicDrawerProps,
 } from "../../../shared/components";
+import { useAnalytics } from "../../../shared/hooks";
+import { ANALYTICS_EVENTS } from "../../../shared/services/logger/analytics/constants";
 import { buyerPortalRoutes } from "../../../shared/utils/buyerPortalRoutes";
 import { useRemoveUserFromOrgUnit } from "../../hooks";
 
@@ -26,10 +28,22 @@ export const DeleteUserDrawer = ({
   const [userNameConfirmation, setUserNameConfirmation] = useState("");
 
   const { pushToast } = useUI();
-
   const { orgUnit } = useOrgUnitByUser(user.id);
+  const { trackEvent } = useAnalytics({
+    entityType: "user",
+    entityId: user.id,
+    defaultTimerName: "user_delete",
+    shouldTrackDefaultTimer: true,
+  });
 
   const handleRemoveSuccess = () => {
+    trackEvent(ANALYTICS_EVENTS.USER_DELETED, {
+      user_id: user.id,
+      user_name: user.name,
+      org_unit_id: orgUnit?.id,
+      entity_type: "user",
+    });
+
     pushToast({
       message: "User successfully deleted",
       status: "INFO",
@@ -52,7 +66,14 @@ export const DeleteUserDrawer = ({
   const { removeUserFromOrgUnit, isRemoveUserFromOrgUnitLoading } =
     useRemoveUserFromOrgUnit({
       onSuccess: handleRemoveSuccess,
-      onError: () => {
+      onError: (error) => {
+        trackEvent(ANALYTICS_EVENTS.USER_DELETE_ERROR, {
+          entity_id: user.id,
+          user_name: user.name,
+          error_message: error instanceof Error ? error.message : String(error),
+          org_unit_id: orgUnit?.id,
+        });
+
         pushToast({
           message: "An error occurred while deleting the user",
           status: "ERROR",

package/src/features/users/components/UpdateUserDrawer/UpdateUserDrawer.tsx

@@ -1,4 +1,4 @@
-import { useState } from "react";
+import { useRef, useState } from "react";
 
 import { Skeleton, useUI } from "@faststore/ui";
 
@@ -10,6 +10,8 @@ import {
   ErrorMessage,
   InputText,
 } from "../../../shared/components";
+import { useAnalytics } from "../../../shared/hooks";
+import { ANALYTICS_EVENTS } from "../../../shared/services/logger/analytics/constants";
 import { maskPhoneNumber } from "../../../shared/utils/phoneNumber";
 import { useGetUserById, useUpdateUser } from "../../hooks";
 
@@ -29,16 +31,25 @@ export const UpdateUserDrawer = ({
   ...props
 }: UpdateUserDrawerProps) => {
   const { pushToast } = useUI();
+  const { trackEntityEdited, trackEntityEditError } = useAnalytics({
+    entityType: "user",
+    entityId: userId,
+    defaultTimerName: "user_edit",
+    shouldTrackDefaultTimer: true,
+  });
+  const initialRolesRef = useRef<string[]>([]);
 
   const { isUserLoading } = useGetUserById(
     { orgUnitId, userId },
     {
       onSuccess: (data) => {
+        const userRoles = data?.roles ? data.roles : [];
+        initialRolesRef.current = userRoles;
         setForm({
           name: data?.name ?? "",
           email: data?.email ?? "",
           phone: data?.phone ?? "",
-          roles: data?.roles ? data.roles : [],
+          roles: userRoles,
         });
       },
       onError: () => {
@@ -74,6 +85,16 @@ export const UpdateUserDrawer = ({
   };
 
   const handleUpdateUserSuccess = () => {
+    trackEntityEdited(ANALYTICS_EVENTS.USER_EDITED, {
+      user_id: userId,
+      user_name: name,
+      user_phone: phone,
+      old_roles: initialRolesRef.current,
+      new_roles: roles,
+      roles_count: roles.length,
+      org_unit_id: orgUnitId,
+    });
+
     pushToast({
       message: "User successfully updated",
       status: "INFO",
@@ -84,7 +105,17 @@ export const UpdateUserDrawer = ({
 
   const { updateUser, isUpdateUserLoading } = useUpdateUser({
     onSuccess: handleUpdateUserSuccess,
-    onError: () => {
+    onError: (error) => {
+      trackEntityEditError(
+        ANALYTICS_EVENTS.USER_EDIT_ERROR,
+        "user",
+        userId,
+        error,
+        {
+          org_unit_id: orgUnitId,
+        }
+      );
+
       pushToast({
         message: "Failed to update user",
         status: "ERROR",
@@ -94,7 +125,17 @@ export const UpdateUserDrawer = ({
 
   const { updateRoles, isUpdateRolesLoading } = useUpdateRoles({
     onSuccess: handleUpdateUserSuccess,
-    onError: () => {
+    onError: (error) => {
+      trackEntityEditError(
+        ANALYTICS_EVENTS.USER_EDIT_ERROR,
+        "user",
+        userId,
+        error,
+        {
+          org_unit_id: orgUnitId,
+        }
+      );
+
       pushToast({
         message: "Failed to update user",
         status: "ERROR",