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

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";

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;