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

package/src/features/custom-fields/components/DeleteCustomFieldValueDrawer/DeleteCustomFieldValueDrawer.tsx

@@ -2,11 +2,12 @@ import { useUI } from "@faststore/ui";
 
 import { BasicDrawerProps } from "../../../shared/components";
 import { DeleteEntityDrawer } from "../../../shared/components/CustomField/delete-custom-field/DeleteCustomFieldDrawer";
-import { useBuyerPortal } from "../../../shared/hooks";
+import { useAnalytics, useBuyerPortal } from "../../../shared/hooks";
 import {
   useDeleteCustomFieldValue,
   useDeleteCustomFieldValueToUnitScope,
 } from "../../../shared/hooks/custom-field";
+import { ANALYTICS_EVENTS } from "../../../shared/services/logger/analytics/constants";
 import { CustomFieldData } from "../../types";
 
 export interface DeleteCustomFieldValueDrawerProps
@@ -36,12 +37,29 @@ export function DeleteCustomFieldValueDrawer({
   const {
     clientContext: { cookie },
   } = useBuyerPortal();
+  const { trackEvent } = useAnalytics({
+    entityType: "custom_field",
+    entityId: currentData?.id,
+    defaultTimerName: "custom_field_delete",
+    shouldTrackDefaultTimer: !!currentData,
+  });
+
   const {
     mutate: deleteCustomFieldValueToUnitScope,
     isLoading: isLoadingDeleteCustomFieldValueToUnitScope,
   } = useDeleteCustomFieldValueToUnitScope({
     options: {
       onSuccess: () => {
+        trackEvent(ANALYTICS_EVENTS.CUSTOM_FIELD_DELETED, {
+          custom_field_type: customField,
+          custom_field_id: currentData?.id,
+          custom_field_name: currentData?.value,
+          delete_mode: "unitScope",
+          org_unit_id: unitId,
+          contract_id: contractId,
+          entity_type: "custom_field",
+        });
+
         pushToast({
           message: `${customField} removed successfully`,
           status: "INFO",
@@ -50,11 +68,25 @@ export function DeleteCustomFieldValueDrawer({
         close();
         refetch();
       },
-      onError: (error) =>
+      onError: (error) => {
+        const errorMessage = typeof error === "string" ? error : error.message;
+
+        trackEvent(ANALYTICS_EVENTS.CUSTOM_FIELD_DELETE_ERROR, {
+          entity_type: "custom_field",
+          entity_id: currentData?.id,
+          custom_field_type: customField,
+          custom_field_name: currentData?.value,
+          delete_mode: "unitScope",
+          org_unit_id: unitId,
+          contract_id: contractId,
+          error_message: errorMessage,
+        });
+
         pushToast({
           message: error.message,
           status: "ERROR",
-        }),
+        });
+      },
     },
   });
 
@@ -64,6 +96,16 @@ export function DeleteCustomFieldValueDrawer({
   } = useDeleteCustomFieldValue({
     options: {
       onSuccess: () => {
+        trackEvent(ANALYTICS_EVENTS.CUSTOM_FIELD_DELETED, {
+          custom_field_type: customField,
+          custom_field_id: currentData?.id,
+          custom_field_name: currentData?.value,
+          delete_mode: "contract",
+          org_unit_id: unitId,
+          contract_id: contractId,
+          entity_type: "custom_field",
+        });
+
         pushToast({
           message: `${customField} deleted successfully`,
           status: "INFO",
@@ -72,11 +114,25 @@ export function DeleteCustomFieldValueDrawer({
         close();
         refetch();
       },
-      onError: (error) =>
+      onError: (error) => {
+        const errorMessage = typeof error === "string" ? error : error.message;
+
+        trackEvent(ANALYTICS_EVENTS.CUSTOM_FIELD_DELETE_ERROR, {
+          entity_type: "custom_field",
+          entity_id: currentData?.id,
+          custom_field_type: customField,
+          custom_field_name: currentData?.value,
+          delete_mode: "contract",
+          org_unit_id: unitId,
+          contract_id: contractId,
+          error_message: errorMessage,
+        });
+
         pushToast({
           message: error.message,
           status: "ERROR",
-        }),
+        });
+      },
     },
   });
 

package/src/features/custom-fields/components/UpdateCustomFieldValueDrawer/UpdateCustomFieldValueDrawer.tsx

@@ -1,8 +1,9 @@
 import { useUI } from "@faststore/ui";
 
 import { UpdateEntityDrawer } from "../../../shared/components/CustomField/update-custom-field/UpdateCustomFieldDrawer";
-import { useBuyerPortal } from "../../../shared/hooks";
+import { useAnalytics, useBuyerPortal } from "../../../shared/hooks";
 import { useUpdateCustomFieldValue } from "../../../shared/hooks/custom-field";
+import { ANALYTICS_EVENTS } from "../../../shared/services/logger/analytics/constants";
 import { CustomFieldData } from "../../types";
 
 import type { BasicDrawerProps } from "../../../shared/components";
@@ -29,12 +30,27 @@ export function UpdateCustomFieldValueDrawer({
   const {
     clientContext: { cookie },
   } = useBuyerPortal();
+  const { trackEntityEdited, trackEntityEditError } = useAnalytics({
+    entityType: "custom_field",
+    entityId: currentData?.id,
+    defaultTimerName: "custom_field_edit",
+    shouldTrackDefaultTimer: !!currentData,
+  });
+
   const {
     mutate: updateCustomFieldValue,
     isLoading: isLoadignUpdateCustomFieldValue,
   } = useUpdateCustomFieldValue({
     options: {
       onSuccess: () => {
+        trackEntityEdited(ANALYTICS_EVENTS.CUSTOM_FIELD_EDITED, {
+          custom_field_type: customField,
+          custom_field_id: currentData?.id,
+          custom_field_old_name: currentData?.value,
+          org_unit_id: unitId,
+          contract_id: contractId,
+        });
+
         pushToast({
           message: `${customField} renamed successfully`,
           status: "INFO",
@@ -43,11 +59,24 @@ export function UpdateCustomFieldValueDrawer({
         close();
         refetch();
       },
-      onError: (error) =>
+      onError: (error) => {
+        trackEntityEditError(
+          ANALYTICS_EVENTS.CUSTOM_FIELD_EDIT_ERROR,
+          "custom_field",
+          currentData?.id ?? "",
+          error,
+          {
+            custom_field_type: customField,
+            org_unit_id: unitId,
+            contract_id: contractId,
+          }
+        );
+
         pushToast({
           message: error.message,
           status: "ERROR",
-        }),
+        });
+      },
     },
   });
 

package/src/features/org-units/components/CreateOrgUnitDrawer/CreateOrgUnitDrawer.tsx

@@ -12,6 +12,8 @@ import {
   InputText,
   Icon,
 } from "../../../shared/components";
+import { useAnalytics } from "../../../shared/hooks";
+import { ANALYTICS_EVENTS } from "../../../shared/services/logger/analytics/constants";
 import { buyerPortalRoutes } from "../../../shared/utils/buyerPortalRoutes";
 import { useCreateNewOrgUnit } from "../../hooks";
 
@@ -34,6 +36,11 @@ export const CreateOrgUnitDrawer = ({
 }: CreateOrgUnitDrawerProps) => {
   const { pushToast } = useUI();
   const router = useRouter();
+  const { trackEntityCreated, trackEntityCreateError } = useAnalytics({
+    entityType: "org_unit",
+    defaultTimerName: "org_unit_creation",
+    shouldTrackDefaultTimer: true,
+  });
 
   const [parentOrgUnit, setParentOrgUnit] = useState(
     initialOrgUnit ?? options[0]
@@ -45,6 +52,12 @@ export const CreateOrgUnitDrawer = ({
   const handleCreateNewOrgUnitSuccess = (
     data: AwaitedType<typeof createNewOrgUnitService>
   ) => {
+    trackEntityCreated(ANALYTICS_EVENTS.ORG_UNIT_CREATED, "org_unit", {
+      org_unit_name: name,
+      parent_org_unit_id: parentOrgUnit?.id,
+      parent_org_unit_name: parentOrgUnit?.name,
+    });
+
     pushToast({
       message: "Organizational unit added successfully",
       status: "INFO",
@@ -77,6 +90,11 @@ export const CreateOrgUnitDrawer = ({
         description: string;
       };
 
+      trackEntityCreateError(ANALYTICS_EVENTS.ORG_UNIT_CREATE_ERROR, err, {
+        parent_org_unit_id: parentOrgUnit?.id,
+        error_type: error.code || "unknown",
+      });
+
       if (error.code === "InvalidOrganizationUnitName") {
         pushToast({
           message: "An organizational unit with the same name already exists",

package/src/features/org-units/components/DeleteOrgUnitDrawer/DeleteOrgUnitDrawer.tsx

@@ -11,6 +11,8 @@ import {
   InputText,
   type BasicDrawerProps,
 } from "../../../shared/components";
+import { useAnalytics } from "../../../shared/hooks";
+import { ANALYTICS_EVENTS } from "../../../shared/services/logger/analytics/constants";
 import { useGetUserByOrgUnitId } from "../../../users/hooks/useGetUserByOrgUnitId";
 import { useChildrenOrgUnits } from "../../hooks";
 import { useDeleteOrgUnit } from "../../hooks/useDeleteOrgUnit";
@@ -31,6 +33,12 @@ export const DeleteOrgUnitDrawer = ({
   const { childrenOrgUnits } = useChildrenOrgUnits(id, name);
   const { users } = useGetUserByOrgUnitId(id);
   const { pushToast } = useUI();
+  const { trackEvent } = useAnalytics({
+    entityType: "org_unit",
+    entityId: id,
+    defaultTimerName: "org_unit_delete",
+    shouldTrackDefaultTimer: true,
+  });
 
   const [confirmName, setConfirmName] = useState("");
   const [isTouched, setIsTouched] = useState(false);
@@ -39,6 +47,13 @@ export const DeleteOrgUnitDrawer = ({
     Boolean(childrenOrgUnits?.nodes?.length) || Boolean(users?.length);
 
   const handleDeleteOrgUnitSuccess = () => {
+    trackEvent(ANALYTICS_EVENTS.ORG_UNIT_DELETED, {
+      org_unit_id: id,
+      org_unit_name: name,
+      entity_type: "org_unit",
+      had_children: hasChildren,
+    });
+
     pushToast({
       message: "Organizational unit deleted successfully",
       status: "INFO",
@@ -55,6 +70,19 @@ export const DeleteOrgUnitDrawer = ({
 
   const { deleteOrgUnit, isDeleteOrgUnitLoading } = useDeleteOrgUnit({
     onSuccess: handleDeleteOrgUnitSuccess,
+    onError: (error) => {
+      trackEvent(ANALYTICS_EVENTS.ORG_UNIT_DELETE_ERROR, {
+        entity_id: id,
+        org_unit_name: name,
+        error_message: error instanceof Error ? error.message : String(error),
+        had_children: hasChildren,
+      });
+
+      pushToast({
+        message: "An error occurred while deleting the organizational unit",
+        status: "ERROR",
+      });
+    },
   });
 
   const handleDelete = () => {

package/src/features/org-units/components/UpdateOrgUnitDrawer/UpdateOrgUnitDrawer.tsx

@@ -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 { buyerPortalRoutes } from "../../../shared/utils/buyerPortalRoutes";
 import { useUpdateOrgUnit } from "../../hooks";
 
@@ -30,11 +32,23 @@ export const UpdateOrgUnitDrawer = ({
 }: UpdateOrgUnitDrawerProps) => {
   const router = useRouter();
   const { pushToast } = useUI();
+  const { trackEntityEdited, trackEntityEditError } = useAnalytics({
+    entityType: "org_unit",
+    entityId: id,
+    defaultTimerName: "org_unit_edit",
+    shouldTrackDefaultTimer: true,
+  });
   const [name, setName] = useState(initialName);
 
   const [isTouched, setIsTouched] = useState(false);
 
   const handleSuccess = () => {
+    trackEntityEdited(ANALYTICS_EVENTS.ORG_UNIT_EDITED, {
+      org_unit_id: id,
+      org_unit_old_name: initialName,
+      org_unit_new_name: name,
+    });
+
     pushToast({
       message: "Organizational unit successfully edited",
       status: "INFO",
@@ -64,6 +78,20 @@ export const UpdateOrgUnitDrawer = ({
 
   const { updateOrgUnit, isUpdateOrgUnitLoading } = useUpdateOrgUnit({
     onSuccess: handleSuccess,
+    onError: (error) => {
+      trackEntityEditError(
+        ANALYTICS_EVENTS.ORG_UNIT_EDIT_ERROR,
+        "org_unit",
+        id,
+        error,
+        {}
+      );
+
+      pushToast({
+        message: "An error occurred while editing the organizational unit",
+        status: "ERROR",
+      });
+    },
   });
 
   const handleConfirmClick = () => {

package/src/features/shared/hooks/analytics/types.ts

@@ -0,0 +1,14 @@
+/**
+ * Timer tracking for multi-step flows
+ */
+export interface AnalyticsTimer {
+  startTime: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface UseAnalyticsConfig {
+  entityType: string;
+  defaultTimerName: string;
+  entityId?: string;
+  shouldTrackDefaultTimer?: boolean;
+}

package/src/features/shared/hooks/analytics/useAnalytics.ts

@@ -0,0 +1,249 @@
+import { useCallback, useEffect, useRef } from "react";
+
+import { useDataIngestionApi } from "../../services/logger/analytics/analytics";
+
+import type { AnalyticsTimer, UseAnalyticsConfig } from "./types";
+
+export function useAnalytics(options: UseAnalyticsConfig) {
+  const { entityType, entityId, defaultTimerName, shouldTrackDefaultTimer } =
+    options;
+  const { sendEvent } = useDataIngestionApi();
+  const timers = useRef<Map<string, AnalyticsTimer>>(new Map());
+
+  useEffect(() => {
+    if (shouldTrackDefaultTimer) {
+      startTimer(defaultTimerName, {
+        entity_type: entityType,
+        entity_id: entityId,
+      });
+    }
+  }, []);
+
+  const withDefaults = useCallback(
+    (properties?: Record<string, unknown>) => ({
+      ...properties,
+      ...(entityId && { entity_id: entityId }),
+      ...(entityType && { entity_type: entityType }),
+    }),
+    [entityType, entityId]
+  );
+
+  /**
+   * Track a generic event
+   * @param eventName - Unique name for the event
+   * @param properties - Additional properties to track
+   */
+  const trackEvent = useCallback(
+    (eventName: string, properties?: Record<string, unknown>) => {
+      sendEvent({
+        event_name: eventName,
+        event_category: "click",
+        metadata: {
+          ...withDefaults(properties),
+        },
+      });
+    },
+    [sendEvent]
+  );
+
+  /**
+   * Track errors
+   * @param eventName - Name of the event where error occurred
+   * @param error - Error object or message
+   * @param context - Additional context about the error
+   */
+  const trackError = useCallback(
+    (
+      eventName: string,
+      error: Error | string,
+      context?: {
+        entityType?: string;
+        entityId?: string;
+        isNew?: boolean;
+        operation?: string;
+      }
+    ) => {
+      const errorMessage = typeof error === "string" ? error : error.message;
+      const errorStack = typeof error === "string" ? undefined : error.stack;
+
+      const errorData: Record<string, unknown> = {
+        error_message: errorMessage,
+        error_type: typeof error === "string" ? "string" : error.name,
+        error_stack: errorStack,
+        ...withDefaults(context),
+        is_new_entity: context?.isNew ?? false,
+        operation: context?.operation,
+      };
+
+      sendEvent({
+        event_name: eventName,
+        event_category: "error",
+        is_new: context?.isNew,
+        metadata: errorData,
+      });
+    },
+    [sendEvent]
+  );
+
+  /**
+   * Start a timer for tracking duration
+   * @param timerName - Unique name for the timer
+   * @param metadata - Optional metadata to store with the timer
+   */
+  const startTimer = useCallback(
+    (timerName: string, metadata?: Record<string, unknown>) => {
+      timers.current.set(timerName, {
+        startTime: Date.now(),
+        metadata,
+      });
+    },
+    [entityType, entityId]
+  );
+
+  /**
+   * End a timer and track the duration
+   * @param timerName - Name of the timer to end
+   * @returns Duration in milliseconds, or null if timer not found
+   */
+  const endTimer = useCallback(
+    (timerName: string): number | null => {
+      const timer = timers.current.get(timerName);
+
+      if (!timer) {
+        console.warn(`Timer "${timerName}" not found`);
+        return null;
+      }
+
+      const duration = Date.now() - timer.startTime;
+      timers.current.delete(timerName);
+
+      return duration;
+    },
+    [entityType, entityId]
+  );
+
+  /**
+   * Generic method: Track entity creation with custom event name
+   * @param eventName - Specific event name (e.g., ANALYTICS_EVENTS.BUDGET_CREATED)
+   * @param entityType - Type of entity (e.g., 'budget', 'buying_policy')
+   * @param properties - Additional properties to track
+   */
+  const trackEntityCreated = useCallback(
+    (
+      eventName: string,
+      entityType: string,
+      properties?: Record<string, unknown>
+    ) => {
+      const duration = endTimer(defaultTimerName);
+      if (duration) {
+        properties = {
+          ...withDefaults(properties),
+          ...(duration !== null && { time_to_create_ms: duration }),
+        };
+      }
+
+      sendEvent({
+        event_name: eventName,
+        event_category: "creation",
+        entity_type: entityType,
+        metadata: withDefaults(properties),
+      });
+    },
+    [sendEvent]
+  );
+
+  /**
+   * Generic method: Track entity editing with custom event name
+   * @param eventName - Specific event name (e.g., ANALYTICS_EVENTS.BUDGET_EDITED)
+   * @param entityType - Type of entity (e.g., 'budget', 'buying_policy')
+   * @param entityId - ID of the entity being edited
+   * @param properties - Additional properties to track
+   */
+  const trackEntityEdited = useCallback(
+    (eventName: string, properties?: Record<string, unknown>) => {
+      sendEvent({
+        event_name: eventName,
+        event_category: "edition",
+        entity_type: entityType,
+        entity_id: entityId,
+        metadata: withDefaults(properties),
+      });
+    },
+    [sendEvent]
+  );
+
+  /**
+   * Generic method: Track entity creation error with custom event name
+   * @param eventName - Specific error event name (e.g., ANALYTICS_EVENTS.BUDGET_CREATE_ERROR)
+   * @param entityType - Type of entity (e.g., 'budget', 'buying_policy')
+   * @param error - Error object or message
+   * @param properties - Additional properties to track
+   */
+  const trackEntityCreateError = useCallback(
+    (
+      eventName: string,
+      error: Error | string,
+      properties?: Record<string, unknown>
+    ) => {
+      const duration = endTimer(defaultTimerName);
+      if (duration) {
+        properties = {
+          ...withDefaults(properties),
+          ...(duration !== null && { time_to_error_ms: duration }),
+        };
+      }
+
+      trackError(eventName, error, {
+        entityType: entityType,
+        entityId: entityId,
+        isNew: true,
+        operation: "create",
+        ...withDefaults(properties),
+      });
+    },
+    [trackError, entityType, entityId]
+  );
+
+  /**
+   * Generic method: Track entity edit error with custom event name
+   * @param eventName - Specific error event name (e.g., ANALYTICS_EVENTS.BUDGET_EDIT_ERROR)
+   * @param entityType - Type of entity (e.g., 'budget', 'buying_policy')
+   * @param entityId - ID of the entity being edited
+   * @param error - Error object or message
+   * @param properties - Additional properties to track
+   */
+  const trackEntityEditError = useCallback(
+    (
+      eventName: string,
+      entityType: string,
+      entityId: string,
+      error: Error | string,
+      properties?: Record<string, unknown>
+    ) => {
+      trackError(eventName, error, {
+        entityType,
+        entityId,
+        isNew: false,
+        operation: "update",
+        ...withDefaults(properties),
+      });
+    },
+    [trackError]
+  );
+
+  return {
+    // Generic methods
+    trackEvent,
+    trackError,
+
+    // Timer methods
+    startTimer,
+    endTimer,
+
+    // Entity-specific generic methods (for Budget, Buying Policy, etc.)
+    trackEntityCreated,
+    trackEntityEdited,
+    trackEntityCreateError,
+    trackEntityEditError,
+  };
+}

package/src/features/shared/hooks/index.ts

@@ -14,3 +14,4 @@ export { usePageItems, type UsePageItemsProps } from "./usePageItems";
 export { useRouterLoading } from "./useRouterLoading";
 export { useLogger } from "./useLogger";
 export { useGetDependenciesVersion } from "./useGetDependenciesVersion";
+export { useAnalytics } from "./analytics/useAnalytics";