@vtex/faststore-plugin-buyer-portal 2.0.25 → 2.0.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vtex/faststore-plugin-buyer-portal",
-  "version": "2.0.25",
+  "version": "2.0.26",
   "description": "A plugin for faststore with buyer portal",
   "main": "index.js",
   "files": [

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

@@ -104,7 +104,8 @@ export const CreateOrgUnitDrawer = ({
 
       trackEntityCreateError(ANALYTICS_EVENTS.ORG_UNIT_CREATE_ERROR, err, {
         parent_org_unit_id: parentOrgUnit?.id,
-        error_type: error.code || "unknown",
+        errorType:
+          error.code === "InvalidOrganizationUnitName" ? "conflict" : undefined,
       });
 
       if (error.code === "InvalidOrganizationUnitName") {

package/src/features/shared/hooks/analytics/__tests__/buildErrorEventMetadata.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from "vitest";
+
+import { ClientError } from "../../../clients/Client";
+import { buildErrorEventMetadata } from "../buildErrorEventMetadata";
+
+describe("buildErrorEventMetadata", () => {
+  it("never includes error_message or error_stack, regardless of error shape", () => {
+    const error = new Error("email: alice@vtex.com, id: 123");
+
+    const result = buildErrorEventMetadata(error, undefined, {});
+
+    expect(result).not.toHaveProperty("error_message");
+    expect(result).not.toHaveProperty("error_stack");
+    expect(JSON.stringify(result)).not.toContain("alice@vtex.com");
+  });
+
+  it("never includes error_message or error_stack for string errors", () => {
+    const result = buildErrorEventMetadata("raw string error", undefined, {});
+
+    expect(result).not.toHaveProperty("error_message");
+    expect(result).not.toHaveProperty("error_stack");
+  });
+
+  it("includes error_type and error_code derived from classifyError", () => {
+    const error = new ClientError("boom", { status: 403 });
+
+    const result = buildErrorEventMetadata(
+      error,
+      { operation: "edit" },
+      { entityType: "budget" }
+    );
+
+    expect(result.error_type).toBe("permission_denied");
+    expect(result.error_code).toBe("budget.edit.permission_denied");
+  });
+
+  it("prefers an explicit errorType hint over status inference", () => {
+    const error = new ClientError("nope", { status: 409 });
+
+    const result = buildErrorEventMetadata(
+      error,
+      {
+        errorType: "user_already_exists",
+        entityType: "user",
+        operation: "create",
+      },
+      {}
+    );
+
+    expect(result.error_type).toBe("user_already_exists");
+    expect(result.error_code).toBe("user.create.user_already_exists");
+  });
+
+  it("does not leak the errorType hint itself as a stray field", () => {
+    const result = buildErrorEventMetadata(
+      "boom",
+      { errorType: "validation" },
+      {}
+    );
+
+    expect(result).not.toHaveProperty("errorType");
+  });
+
+  it("a caller-supplied ad-hoc error_type property in context can never override the classified value", () => {
+    const error = new ClientError("boom", { status: 403 });
+
+    const result = buildErrorEventMetadata(
+      error,
+      { error_type: "totally_made_up" } as never,
+      {}
+    );
+
+    expect(result.error_type).toBe("permission_denied");
+  });
+
+  it("sets is_new_entity to false by default and true when isNew is passed", () => {
+    expect(buildErrorEventMetadata("boom", undefined, {}).is_new_entity).toBe(
+      false
+    );
+    expect(
+      buildErrorEventMetadata("boom", { isNew: true }, {}).is_new_entity
+    ).toBe(true);
+  });
+
+  it("applies entity_type/entity_id defaults from the hook config, and passes through operation", () => {
+    const result = buildErrorEventMetadata(
+      "boom",
+      { operation: "create" },
+      {
+        entityType: "org_unit",
+        entityId: "abc",
+      }
+    );
+
+    expect(result.entity_type).toBe("org_unit");
+    expect(result.entity_id).toBe("abc");
+    expect(result.operation).toBe("create");
+  });
+
+  it("preserves arbitrary pass-through properties from context", () => {
+    const result = buildErrorEventMetadata(
+      "boom",
+      { parent_org_unit_id: "org-1" } as never,
+      {}
+    );
+
+    expect(result.parent_org_unit_id).toBe("org-1");
+  });
+});

package/src/features/shared/hooks/analytics/__tests__/classifyError.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, it } from "vitest";
+
+import { ClientError } from "../../../clients/Client";
+import { classifyError } from "../classifyError";
+
+describe("classifyError", () => {
+  describe("explicit hint precedence", () => {
+    it("uses a valid explicit hint over everything else", () => {
+      const error = new ClientError("conflict", { status: 500 });
+
+      const result = classifyError(error, "user_already_exists");
+
+      expect(result.error_type).toBe("user_already_exists");
+    });
+
+    it("ignores an invalid/unknown hint and falls back to status inference", () => {
+      const error = new ClientError("nope", { status: 403 });
+
+      const result = classifyError(error, "not_a_real_error_type" as never);
+
+      expect(result.error_type).toBe("permission_denied");
+    });
+  });
+
+  describe("HTTP status mapping", () => {
+    it.each([
+      [409, "conflict"],
+      [400, "validation"],
+      [422, "validation"],
+      [403, "permission_denied"],
+      [404, "not_found"],
+      [429, "rate_limited"],
+      [500, "server_error"],
+      [503, "server_error"],
+      [599, "server_error"],
+    ] as const)("maps status %d to %s", (status, expected) => {
+      const error = new ClientError("boom", { status });
+
+      const result = classifyError(error);
+
+      expect(result.error_type).toBe(expected);
+    });
+
+    it("does not map 401 to permission_denied (falls through to unknown)", () => {
+      const error = new ClientError("unauthorized", { status: 401 });
+
+      const result = classifyError(error);
+
+      expect(result.error_type).toBe("unknown");
+    });
+
+    it("falls back to unknown for an unmapped status", () => {
+      const error = new ClientError("teapot", { status: 418 });
+
+      const result = classifyError(error);
+
+      expect(result.error_type).toBe("unknown");
+    });
+  });
+
+  describe("network fallback", () => {
+    it("classifies a fetch-level TypeError with no status as network", () => {
+      const error = new TypeError("Failed to fetch");
+
+      const result = classifyError(error);
+
+      expect(result.error_type).toBe("network");
+    });
+
+    it("classifies AbortError as network", () => {
+      const error = new Error("aborted");
+      error.name = "AbortError";
+
+      const result = classifyError(error);
+
+      expect(result.error_type).toBe("network");
+    });
+
+    it("classifies TimeoutError as network", () => {
+      const error = new Error("timed out");
+      error.name = "TimeoutError";
+
+      const result = classifyError(error);
+
+      expect(result.error_type).toBe("network");
+    });
+  });
+
+  describe("unknown fallback", () => {
+    it("classifies a plain Error with no status/network signature as unknown", () => {
+      const error = new Error("something broke");
+
+      const result = classifyError(error);
+
+      expect(result.error_type).toBe("unknown");
+    });
+
+    it("classifies a string error as unknown when no hint is given", () => {
+      const result = classifyError("Something failed");
+
+      expect(result.error_type).toBe("unknown");
+    });
+
+    it("respects an explicit hint even when the error is a string", () => {
+      const result = classifyError("Something failed", "validation");
+
+      expect(result.error_type).toBe("validation");
+    });
+  });
+
+  describe("error_code format", () => {
+    it("builds a 3-segment error_code from entity/operation context and the resolved error_type", () => {
+      const error = new ClientError("boom", { status: 403 });
+
+      const result = classifyError(error, undefined, {
+        entityType: "budget",
+        operation: "edit",
+      });
+
+      expect(result.error_code).toBe("budget.edit.permission_denied");
+    });
+
+    it("replaces missing entity_type/operation with the literal 'unknown'", () => {
+      const error = new TypeError("Failed to fetch");
+
+      const result = classifyError(error);
+
+      expect(result.error_code).toBe("unknown.unknown.network");
+    });
+
+    it("uses the explicit hint as the reason segment", () => {
+      const result = classifyError("boom", "user_already_exists", {
+        entityType: "user",
+        operation: "create",
+      });
+
+      expect(result.error_code).toBe("user.create.user_already_exists");
+    });
+  });
+
+  describe("never throws", () => {
+    it("does not throw for weird/malformed input", () => {
+      expect(() =>
+        classifyError({} as unknown as Error, undefined, {})
+      ).not.toThrow();
+    });
+  });
+});

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

@@ -0,0 +1,60 @@
+import { classifyError } from "./classifyError";
+
+import type { ErrorType } from "./types";
+
+export interface ErrorEventContext {
+  entityType?: string;
+  entityId?: string;
+  isNew?: boolean;
+  operation?: string;
+  /** Explicit classification hint, forwarded to `classifyError` as its `hint`. */
+  errorType?: ErrorType;
+  [key: string]: unknown;
+}
+
+export interface ErrorEventDefaults {
+  entityType?: string;
+  entityId?: string;
+}
+
+/**
+ * Build the `metadata` object for an error analytics event.
+ *
+ * Classifies the error into `error_type`/`error_code` via `classifyError`
+ * and merges in entity/operation context. `error_message` and `error_stack`
+ * are never read from the input error, so they can never end up on the
+ * returned object.
+ *
+ * `error_type` / `error_code` are always applied last, so a stray
+ * caller-supplied property with the same key (e.g. a legacy ad-hoc
+ * `properties.error_type` override) can never take precedence over the
+ * classified value.
+ */
+export function buildErrorEventMetadata(
+  error: Error | string,
+  context: ErrorEventContext | undefined,
+  defaults: ErrorEventDefaults = {}
+): Record<string, unknown> {
+  const { errorType, entityType, entityId, isNew, operation, ...rest } =
+    context ?? {};
+
+  const resolvedEntityType = entityType ?? defaults.entityType;
+  const resolvedEntityId = entityId ?? defaults.entityId;
+
+  const { error_type, error_code } = classifyError(error, errorType, {
+    entityType: resolvedEntityType,
+    operation,
+  });
+
+  return {
+    ...rest,
+    ...(resolvedEntityId !== undefined && { entity_id: resolvedEntityId }),
+    ...(resolvedEntityType !== undefined && {
+      entity_type: resolvedEntityType,
+    }),
+    is_new_entity: isNew ?? false,
+    operation,
+    error_type,
+    error_code,
+  };
+}

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

@@ -0,0 +1,120 @@
+import { ERROR_TYPE_VALUES } from "./types";
+
+import type { ErrorType } from "./types";
+
+/**
+ * HTTP status -> ErrorType mapping used when no explicit classification hint
+ * is provided. 401 is intentionally omitted: it is already handled by
+ * `handleUnauthorizedRedirect` (session redirect) as a distinct flow, so if a
+ * 401 reaches `classifyError` it falls through to "unknown" rather than being
+ * conflated with 403.
+ */
+const STATUS_TO_ERROR_TYPE: Record<number, ErrorType> = {
+  400: "validation",
+  422: "validation",
+  403: "permission_denied",
+  404: "not_found",
+  409: "conflict",
+  429: "rate_limited",
+};
+
+const UNKNOWN_SEGMENT = "unknown";
+
+function isErrorType(value: unknown): value is ErrorType {
+  return (
+    typeof value === "string" &&
+    (ERROR_TYPE_VALUES as readonly string[]).includes(value)
+  );
+}
+
+function getStatus(error: Error | string): number | undefined {
+  if (typeof error === "string") {
+    return undefined;
+  }
+
+  const status = (error as { status?: unknown }).status;
+  return typeof status === "number" ? status : undefined;
+}
+
+function statusToErrorType(status: number | undefined): ErrorType | undefined {
+  if (status === undefined) {
+    return undefined;
+  }
+
+  if (status >= 500 && status <= 599) {
+    return "server_error";
+  }
+
+  return STATUS_TO_ERROR_TYPE[status];
+}
+
+function looksLikeNetworkFailure(error: Error | string): boolean {
+  if (typeof error === "string") {
+    return false;
+  }
+
+  if (error.name === "AbortError" || error.name === "TimeoutError") {
+    return true;
+  }
+
+  return (
+    error.name === "TypeError" &&
+    typeof error.message === "string" &&
+    error.message.toLowerCase().includes("fetch")
+  );
+}
+
+function resolveErrorType(error: Error | string, hint?: ErrorType): ErrorType {
+  if (isErrorType(hint)) {
+    return hint;
+  }
+
+  const mappedFromStatus = statusToErrorType(getStatus(error));
+  if (mappedFromStatus) {
+    return mappedFromStatus;
+  }
+
+  if (looksLikeNetworkFailure(error)) {
+    return "network";
+  }
+
+  return "unknown";
+}
+
+function toSegment(value?: string): string {
+  return value && value.trim() ? value.trim() : UNKNOWN_SEGMENT;
+}
+
+function buildErrorCode(
+  reason: ErrorType,
+  context?: { entityType?: string; operation?: string }
+): string {
+  return `${toSegment(context?.entityType)}.${toSegment(
+    context?.operation
+  )}.${reason}`;
+}
+
+/**
+ * Classify an error into a fixed, business-meaningful `error_type` and a
+ * finer-grained `error_code` for analytics. Pure, synchronous, never throws,
+ * and never reads `error.message` / `error.stack` into the return value.
+ *
+ * Classification precedence: explicit `hint` (if a valid `ErrorType`) > HTTP
+ * status on a `ClientError`-shaped error > network-failure signature >
+ * `"unknown"`.
+ */
+export function classifyError(
+  error: Error | string,
+  hint?: ErrorType,
+  context?: { entityType?: string; operation?: string }
+): { error_type: ErrorType; error_code: string } {
+  try {
+    const error_type = resolveErrorType(error, hint);
+    return { error_type, error_code: buildErrorCode(error_type, context) };
+  } catch {
+    return {
+      error_type: "unknown",
+      error_code: buildErrorCode("unknown", context),
+    };
+  }
+}

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

@@ -22,3 +22,35 @@ export type EntityCreateErrorCorrelationFields = {
   operation_name?: string;
   operation_phase?: string;
 };
+
+/**
+ * Fixed, finite set of business-meaningful error categories emitted as `error_type`
+ * on every error analytics event.
+ *
+ * This is a frozen contract shared with B2BTEAM-3642 (Redshift column + QuickSight
+ * breakdown). Adding a member requires updating the spec
+ * (`specs/b2bteam-3641-error-type-emission.md`) and coordinating with that dataset —
+ * it is not something an individual call site can extend unilaterally.
+ */
+export type ErrorType =
+  | "user_already_exists" // domain-specific conflict: entity/user creation collides with an existing one
+  | "validation" // request rejected due to invalid input (400-class, non-conflict)
+  | "conflict" // generic 409-class or domain conflict other than user_already_exists (e.g. duplicate name)
+  | "permission_denied" // 403-class — actor lacks permission for the operation
+  | "not_found" // 404-class — target entity does not exist
+  | "rate_limited" // 429-class
+  | "network" // fetch-level failure: no response reached the client (offline, DNS, CORS, abort, timeout)
+  | "server_error" // 5xx-class — upstream/server failure
+  | "unknown"; // anything that does not match the above
+
+export const ERROR_TYPE_VALUES: readonly ErrorType[] = [
+  "user_already_exists",
+  "validation",
+  "conflict",
+  "permission_denied",
+  "not_found",
+  "rate_limited",
+  "network",
+  "server_error",
+  "unknown",
+];

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

@@ -2,9 +2,12 @@ import { useCallback, useEffect, useRef } from "react";
 
 import { useDataIngestionApi } from "../../services/logger/analytics/useDataIngestionApi";
 
+import { buildErrorEventMetadata } from "./buildErrorEventMetadata";
+
 import type {
   AnalyticsTimer,
   EntityCreateErrorCorrelationFields,
+  ErrorType,
   UseAnalyticsConfig,
 } from "./types";
 
@@ -65,19 +68,13 @@ export function useAnalytics(options: UseAnalyticsConfig) {
         entityId?: string;
         isNew?: boolean;
         operation?: string;
+        errorType?: ErrorType;
       }
     ) => {
-      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,
-      };
+      const errorData = buildErrorEventMetadata(error, context, {
+        entityType,
+        entityId,
+      });
 
       sendEvent({
         event_name: eventName,
@@ -86,7 +83,7 @@ export function useAnalytics(options: UseAnalyticsConfig) {
         metadata: errorData,
       });
     },
-    [sendEvent]
+    [sendEvent, entityType, entityId]
   );
 
   /**
@@ -186,7 +183,8 @@ export function useAnalytics(options: UseAnalyticsConfig) {
     (
       eventName: string,
       error: Error | string,
-      properties?: Record<string, unknown> & EntityCreateErrorCorrelationFields
+      properties?: Record<string, unknown> &
+        EntityCreateErrorCorrelationFields & { errorType?: ErrorType }
     ) => {
       const duration = endTimer(defaultTimerName);
       if (duration) {
@@ -221,7 +219,7 @@ export function useAnalytics(options: UseAnalyticsConfig) {
       entityType: string,
       entityId: string,
       error: Error | string,
-      properties?: Record<string, unknown>
+      properties?: Record<string, unknown> & { errorType?: ErrorType }
     ) => {
       trackError(eventName, error, {
         entityType,

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

@@ -1,3 +1,5 @@
+import type { ErrorType } from "../../../hooks/analytics/types";
+
 /**
  * Actor classification for analytics events (internal VTEX vs external).
  */
@@ -70,12 +72,17 @@ export interface StepTimingProperties {
 }
 
 /**
- * Error tracking properties
+ * Error tracking properties.
+ *
+ * `error_message` / `error_stack` are intentionally not modeled here — they
+ * must never be emitted to the Data Ingestion API (see
+ * `specs/b2bteam-3641-error-type-emission.md`). `error_type` is the fixed,
+ * finite `ErrorType` enum; `error_code` is the `"{entity}.{op}.{reason}"`
+ * string built by `classifyError`.
  */
 export interface ErrorEventProperties {
-  error_message: string;
-  error_type?: string;
-  error_stack?: string;
+  error_type: ErrorType;
+  error_code: string;
   entity_type?: string;
   entity_id?: string;
   is_new_entity: boolean;

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

@@ -22,4 +22,4 @@ export const SCOPE_KEYS = {
   CREDIT_CARDS: "creditCards",
 } as const;
 
-export const CURRENT_VERSION = "2.0.25";
+export const CURRENT_VERSION = "2.0.26";

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

@@ -143,10 +143,10 @@ export const CreateUserDrawer = ({
 
       trackEntityCreateError(ANALYTICS_EVENTS.USER_CREATE_ERROR, err, {
         org_unit_id: orgUnitId,
-        error_type:
+        errorType:
           error.code === "USER_ALREADY_EXISTS"
             ? "user_already_exists"
-            : "unknown",
+            : undefined,
       });
 
       setUserAlreadyInUse({

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

@@ -227,7 +227,10 @@ export const CreateUserDrawerWithUsername = ({
 
       trackEntityCreateError(ANALYTICS_EVENTS.USER_CREATE_ERROR, err, {
         org_unit_id: orgUnitId,
-        error_type: error.code || "unknown",
+        errorType:
+          error.code === "EMAIL_ALREADY_EXISTS"
+            ? "user_already_exists"
+            : undefined,
       });
 
       if (error.code === "EMAIL_ALREADY_EXISTS") {